css-hot-loader

CSS Hot Loader

This is a css hot loader, which support hot module replacement for an extracted css file.

Why we need css hot loader

In most cases, we can realize css hot reload by style-loader . But style-loader need inject style tag into document, Before js ready, the web page will have no any style. That is not good experience.

Also, a lots of people thought about that, How can realize hot reload with extract-text-webpack-plugin. For example #30 , #!89.

So I wrote this loader, which supports hot module replacement for an extracted css file.

Install

First install package from npm

$ npm install css-hot-loader --save-dev

Then config webpack.config.js

module: {
  rules: [
    {
      test: /\.css$/,
      use: ['css-hot-loader'].concat(ExtractTextPlugin.extract({
        fallback: 'style-loader',
        use: 'css-loader'
      })),
    },
  ]
}

css-hot-loader should be the first loader before extract-text-webpack-plugin.

Attention

This plugin require the output css file name static. If output file name depend on css content, for example 'bundle.[name].[contenthash].css', HMR reload will fail, more detail refer to #21.

webpack 4

There is an issue to work with webpack4 #37. Please use mini-css-extract-plugin to replace extract-text-webpack-plugin. Config like this:

module: {
  rules: [
    {
      test: /\.css/,
      use: [
        'css-hot-loader',
        MiniCssExtractPlugin.loader,
        'css-loader',
      ],
    },
  ] // end rules
},

webpack 1.x

Config file example should like this

  module: {
    loaders: [{
      test: /\.less$/,
      loaders: [
        'css-hot-loader',
        'extract-text-webpack-plugin',
        'less',
        ...
       ],
      include: path.join(__dirname, 'src')
    }]
  }

options

fileMap

Option to define you css file reload rule. Since 1.1.0 .

For example 'css-hot-loader?fileMap='../css/{fileName}' , which mean

js/foo.js => css/foo.css

Default value is {fileName}.

see #3.

reloadAll

Force reload all css file.

How

The realization principle of this loader is very simple. There are some assumed condition:

1. css required by js , so css also be a js file
2. The name of css file, which need hot reload , is the same as js file excuted.

The secend assumption is often established. If you use extract-text-webpack-plugin , entry foo.js will extract css file foo.css. This principle will help us to locate the url of css file extracted.

Because every css file will be a js module , every css file change can affect a module change. CSS hot loader will accept this kind change, then find extracted css file by document.currentScript.

So when a css file changed, We just need find which css file link element, and reload css file.

License

(The MIT License)