Style Extension for HTML Webpack Plugin

Enhances HtmlWebpackPlugin functionality by enabling inline styles.

This is an extension plugin for the Webpack plugin HtmlWebpackPlugin - a plugin that simplifies the creation of HTML files to serve your webpack bundles.

The raw HtmlWebpackPlugin can bundle CSS assets as <link> elements if used in conjunction with ExtractTextPlugin. This extension plugin offers an alternative - inline <style> elements instead of <link> elements.

Note: this is for inlining <style>'s only - if you wish to inline <scripts>'s please take a look at:

• the HtmlWebpackPlugin inline example based on jade templates;
• the experimental inlining feature of sister plugin script-ext-html-webpack-plugin.

Installation

You must be running webpack v1.x on node v4.x or v5.x.

This plugin is not compatible with Webpack 2 (yet). A one-off compilation is fine but hot reloading will fail.

Install the plugin with npm:

$ npm install --save-dev style-ext-html-webpack-plugin

Basic Usage

The plugin must be added to the webpack config as both a plugin and as the final loader for the CSS assets you wish to be inlined:

module: {
  loaders: [
    { test: /\.css$/, loader: StyleExtHtmlWebpackPlugin.inline() }
  ]           
},
plugins: [
  new HtmlWebpackPlugin(),
  new StyleExtHtmlWebpackPlugin()
]  

The inline loader can be the end of a chain of CSS loaders, though note that any prior loader must output pure CSS, not javascript. This means that css-loader and style-loader cannot be used, though the very useful post-css loader can be:

module: {
  loaders: [
    { test: /\.css$/, loader: StyleExtHtmlWebpackPlugin.inline('postcss-loader') }
  ]           
},
postcss: [
  require('autoprefixer')
],
plugins: [
  new HtmlWebpackPlugin(),
  new StyleExtHtmlWebpackPlugin()
]  

Using with Non-Inlined CSS

You may wish to have only some of your CSS inlined.

This can be achieved by using this plugin alongside webpack's conventional CSS loaders and/or the ExtractTextPlugin. The trick is to define multiple, distinct CSS loader paths in webpack's configuration:

Example: to have stylesheet 1 inlined and stylesheets 2-9 loaded via javascript:

module: {
  loaders: [
    { test: /stylesheet1.css/, loader: StyleExtHtmlWebpackPlugin.inline() },
    { test: /stylesheet[2-9].css/, loader: 'style!css' }
  ]
},
plugins: [
  new HtmlWebpackPlugin(),
  new StyleExtHtmlWebpackPlugin()
]

Example: to have stylesheet 1 inlined and stylesheets 2-9 combined and <link>'d in styles.css:

module: {
  loaders: [
    { test: /stylesheet1.css/, loader: StyleExtHtmlWebpackPlugin.inline() },
    { test: /stylesheet[2-9].css/, loader: ExtractTextPlugin.extract('style-loader', 'css-loader') }
  ]
},
plugins: [
  new HtmlWebpackPlugin(),
  new StyleExtHtmlWebpackPlugin(),
  new ExtractTextPlugin('styles.css')
]

Of course, more sophisticated RegEx's offer more selectivity. Make sure test patterns do not overlap else you will end up with CSS in multiple places.

Minification

The plugin can be configured to use clean-css to minify the inlined CSS.

Note that clean-css is an optional dependency so to use it you must explicitly install it:

$ npm install clean-css

If you forget this you will recieve error: Cannot find module 'clean-css'

Clean-css is enabled by passing the StyleExtHtmlWebpackPlugin constructor a hash with a single property:

• minify: true or, to customise css-clean behaviour, another hash with properties defined in the clean-css docs.

Example: default minification

plugins: [
  new HtmlWebpackPlugin(),
  new StyleExtHtmlWebpackPlugin({
    minify: true
  })
]

Example: customised minification

plugins: [
  new HtmlWebpackPlugin(),
  new StyleExtHtmlWebpackPlugin({
    minify: {
      keepSpecialComments: *,
      roundingPrecision: -1
    }
  })
]

Debugging

If you have problems and want to sort them out yourself(!), this plugin has built-in debugging that may help. It uses the debug utility. Available debug names:

• StyleExtHtmlWebpackPlugin:plugin for the plugin;
• StyleExtHtmlWebpackPlugin:loader for the loader;
• StyleExtHtmlWebpackPlugin:detail for core values (note verbose!);
• or, for all of them: StyleExtHtmlWebpackPlugin:*

Change History

• v1.0.7 - added warning that not compatible with webpack 2
• v1.0.6 - updated tests to match changes in script-ext-html-webpack-plugin
• v1.0.5 - updated code to match changes in semistandard
• v1.0.4 - added debug options
• v1.0.3 - documentation update
• v1.0.2 - documentation update
• v1.0.1 - now plays happily with plugins on same event
• v1.0.0 - initial release

Alternative

Note that an alternative mechanism to inline CSS is possible, using the ExtractTextPlugin and templates - see the HtmlWebpackPlugin example.