CSS Hot Loader

1.4.4 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader for hot module replacement (HMR) of extracted CSS files, specifically designed to work with extract-text-webpack-plugin and mini-css-extract-plugin. Current stable version is 1.4.4, with low release cadence (last release in 2019). Unlike style-loader (which injects styles via <style> tags and causes FOUC), css-hot-loader enables HMR directly on extracted CSS files while preserving the document styles during JavaScript boot. Requires Webpack 4+ and mini-css-extract-plugin; Webpack 5 compatibility is unclear.

Common errors

error Error: Cannot find module 'css-hot-loader' ↓

cause css-hot-loader not installed or not in devDependencies

fix

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

error Module build failed: TypeError: The 'compilation' argument must be an instance of Compilation ↓

cause Incompatible with Webpack 5; css-hot-loader v1.4.4 only supports Webpack 4 and below

fix

Use Webpack 4 or consider alternative loaders like style-loader with HMR

error HMR: hot reload did not trigger when CSS changed ↓

cause Output CSS filename contains [contenthash] or dynamic hash, so the loader cannot find the CSS file to reload

fix

Use a static filename in MiniCssExtractPlugin options: filename: 'bundle.css'

error Uncaught Error: CSS hot loader: cannot get CSS file path for module ↓

cause Incorrect fileMap option or CSS/JS entry name mismatch; the loader expects the CSS file to be named same as the JS module

fix

Ensure CSS file path matches JS module name (e.g., src/foo.js -> dist/foo.css). Use fileMap option if needed

Warnings

breaking Output CSS filename must be static; contenthash in filename breaks HMR ↓

fix Use a static filename like 'bundle.css' or '[name].css' without [contenthash] or [chunkhash]

gotcha css-hot-loader must be placed before MiniCssExtractPlugin.loader in the use array; otherwise HMR won't work ↓

fix Ensure loader order: ['css-hot-loader', MiniCssExtractPlugin.loader, 'css-loader']

gotcha Options must be passed as query string on the loader name, not via options object ↓

fix Use string syntax: 'css-hot-loader?reloadAll' instead of { loader: 'css-hot-loader', options: { reloadAll: true } }

gotcha When using CSS Modules (cssModule option), JS files will also reload on CSS changes, potentially causing full page refresh ↓

fix Only enable cssModule if you need JS to re-execute on CSS change; otherwise omit the option

deprecated extract-text-webpack-plugin usage is deprecated; switch to mini-css-extract-plugin for Webpack 4+ ↓

fix Replace extract-text-webpack-plugin with mini-css-extract-plugin and update loader config accordingly

Install

npm install css-hot-loader

yarn add css-hot-loader

pnpm add css-hot-loader

Imports

css-hot-loader
```
module.exports = { module: { rules: [ { test: /\.css$/, use: ['css-hot-loader', MiniCssExtractPlugin.loader, 'css-loader'] } ] } }
```
Loader is used as a string reference in Webpack config, not imported in JS files. Must be placed before MiniCssExtractPlugin.loader.

fileMap option

wrong

config: { module: { rules: [ { use: ['css-hot-loader', { loader: 'css-hot-loader', options: { fileMap: '../css/{fileName}' } }, ...] } ] } }

correct

config: { module: { rules: [ { use: ['css-hot-loader?fileMap=../css/{fileName}', ...] } ] } }

Options are passed as query string on the loader string; using options object syntax is not supported.

reloadAll option

wrong

config: { module: { rules: [ { use: ['css-hot-loader', { reloadAll: true }, ...] } ] } }

correct

config: { module: { rules: [ { use: ['css-hot-loader?reloadAll', ...] } ] } }

reloadAll is a Boolean flag, enabled by adding the query parameter without a value.

cssModule option

wrong

config: { module: { rules: [ { use: ['css-hot-loader', { cssModule: true }, ...] } ] } }

correct

config: { module: { rules: [ { use: ['css-hot-loader?cssModule', ...] } ] } }

When enabled, CSS module changes also trigger JS reload. Pass as query parameter without value.

Quickstart

Webpack config example using css-hot-loader with mini-css-extract-plugin for HMR on extracted CSS

// webpack.config.js
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist'
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'css-hot-loader',
          MiniCssExtractPlugin.loader,
          'css-loader'
        ]
      }
    ]
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: 'bundle.css'
    })
  ]
};

// src/index.js
import './style.css';
console.log('CSS HMR with extracted file');