Home

Awesome

npm version Dependency Status Build status js-semistandard-style

NPM

Deprecation Warning

tl;dr
This project is no longer maintained. It does not support Webpack 5.

A bit more detail
Any look at the project activity will show that I have not been able to maintain this project adequately.
The advent of version 5 of Webpack requires another bout of refactoring that I simply have no time for.
Consequently v4.1.3 will be the last version of this plugin. My thanks to all users, and especially to all contributors, of this plugin over the years.
My apologies to all those whose webpack 5 migration has been made more complicated by this decision.

But I still want to use the plugin...
Feel free!
My last update works with versions of v4.x of webpack and v4.x of html-webpack-plugin.
Forkers feel free! That's what the licence is for.
In fact, if you fork with an intention to support on-going development, let me know! I'll happily link to your repository here and offer some tips (main one: ditch backward compatibility - it's a pain).
I will formally archive this repository at the end of the 2020.

Summary

If you use HtmlWebpackPlugin and ExtractTextPlugin or MiniCssExtractPlugin to <link> to external stylesheet files, add this plugin to convert the links into <style> elements.

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 or MiniCSSExtractPlugin.
This extension plugin builds on this by moving the CSS content generated by the extract plugins from an external CSS file to an internal <style> element.

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

Installation

Install the plugin with npm:

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

Note: you may see warnings of the following type:

npm WARN html-webpack-plugin@XXX requires a peer of webpack@* but none was installed.

This is fine - for testing, we dynamically download multiple version of webpack and its plugins (via the dynavers module).

Version Compatibility

Compatibility of v4.x of this plugin (node 6 or higher) - see explanations below the table:

WebpackHtmlWebpackPluginExtractTextPluginMiniCssExtractPluginFunctionality
v3.xv3.xv3.x-no HMR
v4.xv3.xv4.x-no HMR
v4.xv3.x-0.7.xno tested HMR, no tested multi-entry
v4.xv4.x-0.7.xno tested HMR, no tested multi-entry, no template styles

Basic Usage

Use Case: Internalize all your CSS

Add the plugin to your webpack config.

The order is important - the plugin must come after HtmlWebpackPlugin and ExtractTextWebpackPlugin:

module: {
  loaders: [
    { test: /\.css$/, loader: ExtractTextPlugin.extract(...)}
  ]
}
plugins: [
  new HtmlWebpackPlugin({...}),
  new ExtractTextWebpackPlugin('styles.css'),
  new StyleExtHtmlWebpackPlugin()  << add the plugin
]

That's it.

Note that for this simple configuration, HtmlWebpackPlugin's inject option must not be false. However, this constraint does not apply if you specify the position - see 'Use Case: Specifying Position of Style Element' below

Use Case: Internalize critical CSS only

Add the plugin and use more than one loader for your CSS:

module: {
  loaders: [
    { test: /critical.css/, loader: ExtractTextPlugin.extract(...)},
    { test: /other.css/, loader: 'style-loader!css-loader'},  << add separate loader
  ]
}
plugins: [
  new HtmlWebpackPlugin({...}),
  new ExtractTextWebpackPlugin('styles.css'),
  new StyleExtHtmlWebpackPlugin()
]

Use Case: Internalize critical CSS with all other CSS in an external file

Use two instances of ExtractTextPlugin and tell StyleExtWebpackPlugin which one to target by giving it the name of the output file:

const internalCSS = new ExtractTextPlugin('internal.css');
const externalCSS = new ExtractTextPlugin('styles.css');
return {
  ...
  module: {
    loaders: [
      { test: /critical.css/, loader: internalCSS.extract(...)},
      { test: /other.css/, loader: externalCSS.extract(...)},
    ]
  }
  plugins: [
    new HtmlWebpackPlugin({...}),
    internalCSS,
    externalCSS,
    new StyleExtHtmlWebpackPlugin('internal.css') << tell the plugin which to target
  ]
}

Use Case: Specifying Position of Style Element

In the above cases, the positioning of the <style element is controlled by the inject option specified by html-webpack-plugin. For more control, you can use an extended, hash version of the configuration. This can have the following properties:

So to put the CSS at the bottom of the <head> element:

module: {
  loaders: [
    { test: /\.css$/, loader: ExtractTextPlugin.extract(...)}
  ]
}
plugins: [
  new HtmlWebpackPlugin({...}),
  new ExtractTextWebpackPlugin('styles.css'),
  new StyleExtHtmlWebpackPlugin({
    position: 'head-bottom'
  })
]

Use Case: Minification/Optimisation

The inlined CSS can be minified/optimised using the extended, hash version of the configuration. Use the minify property with one of the following values:

Default minification:

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

Custom minification:

plugins: [
  ...
  new StyleExtHtmlWebpackPlugin({
    minify: {
      level: {
        1: {
          all: false,
          tidySelectors: true
        }
      }
    }
  })
]

Use Case: Sass/PostCSS Processing etc.

All as per the extract plugin you have chosen.

Use Case: Multiple HTML files

MiniCssExtractPlugin

See the discussion below regarding ExtractTextPlugin.
MiniCssExtractPlugin also supports multiple entry points with chunks.
However a configuration to work with StyleExtWebpackPlugin has not yet been tested.

ExtractTextPlugin

html-webpack-plugin can generate multiple html files if you use multiple instances of the plugin. If you want each html page to be based on different assets (e.g a set of pages) you do this by focussing each html-webpack-plugin instance on a particular entry point via its chunks configuration option.

style-ext-html-webpack-plugin supports this approach by offering the same chunks option. As you also need an instance of extract-text-webpack-plugin, the configuration is quite unwieldy:

...
const page1Extract = new ExtractTextPlugin('page1.css');
const page2Extract = new ExtractTextPlugin('page2.css');
const webpackConfig = {
  ...
  entry: {
    entry1: 'page-1-path/script.js',
    entry2: 'page-2-path/script.js'
  },
  output.filename = '[name].js',
  module.loaders: [
    {
      test: /\.css$/,
      loader: page1Extract.extract('style-loader', 'css-loader'),
      include: [
        'page-1-path'
      ]
    },
    {
      test: /\.css$/,
      loader: page2Extract.extract('style-loader', 'css-loader'),
      include: [
        'page-2-path'
      ]
    }
  ],
  plugins: [
    new HtmlWebpackPlugin({
      chunks: ['entry1'],
      filename: 'page1.html'
    }),
    new HtmlWebpackPlugin({
      chunks: ['entry2'],
      filename: 'page2.html'
    }),
    page1Extract,
    page2Extract,
    new StyleExtHtmlWebpackPlugin({
      chunks: ['entry1']
    }),
    new StyleExtHtmlWebpackPlugin({
      chunks: ['entry2']
    })
  ],
  ...
}
return webpackConfig;

Phew! A loop is recommended instead.

Use Case: Hot Module Replacement

MiniCssExtractPlugin

Hot module replacement should work, but has not been tested.

ExtractTextPlugin

ExtractTextPlugin does not support HMR. If you really need this for your CSS you have two options:

  1. revert to/stick with v2.x of this plugin;
  2. only internalize the CSS on production builds.

The former option is viable if v2.x supports your requirements but that version is no longer maintained hence the second approach is recommended.

For this, use a conditional in your webpack.config to:

const DEBUG = (process.env.NODE_ENV !== 'production');
return {
  ...
  module: {
    loaders: [
      {
        test: /\.css$/,
        loader: DEBUG ? 'style-loader|css-loader' : ExtractTextPlugin.extract({...})
      }
    ]
  },
  plugins: [
    new HtmlWebpackPlugin({...}),
    new ExtractTextPlugin('styles.css'),
    new StyleExtHtmlWebpackPlugin(!DEBUG)
  ]
}

Debugging

If you have any problems, check the HTML file outputted by HtmlWebpackPlugin. As long as it has the showErrors configuration option set (the default), any errors from StyleExt will be displayed there.

Your next step is to simply remove the StyleExtPlugin and check that ExtractTextPlugin works by itself.

If it does and reintroducing StyleExtPlugin still has problems, please raise an issue giving your configuration and, please, DEBUG output. The DEBUG output is generated by the debug tool which is enabled by setting the DEBUG=StyleExt environmental variable:

DEBUG=StyleExt webpack

The output of a working configuration will look something like:

StyleExt constructor: enabled=true, filename=undefined
StyleExt html-webpack-plugin-alter-asset-tags: CSS file in compilation: 'styles.css'
StyleExt html-webpack-plugin-alter-asset-tags: CSS in compilation: @import url(https://fonts.googleapis.com/css?family=Indie+Flower);...
StyleExt html-webpack-plugin-alter-asset-tags: link element found for style path 'styles.css'
StyleExt html-webpack-plugin-alter-asset-tags: completed)

Change History