Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ config: { module: { rules: [ { use: ['css-hot-loader?fileMap=../css/{fileName}', ...] } ] } }
✗ config: { module: { rules: [ { use: ['css-hot-loader', { loader: 'css-hot-loader', options: { fileMap: '../css/{fileName}' } }, ...] } ] } }
Options are passed as query string on the loader string; using options object syntax is not supported.
reloadAll option
✓ config: { module: { rules: [ { use: ['css-hot-loader?reloadAll', ...] } ] } }
✗ config: { module: { rules: [ { use: ['css-hot-loader', { reloadAll: true }, ...] } ] } }
reloadAll is a Boolean flag, enabled by adding the query parameter without a value.
cssModule option
✓ config: { module: { rules: [ { use: ['css-hot-loader?cssModule', ...] } ] } }
✗ config: { module: { rules: [ { use: ['css-hot-loader', { cssModule: true }, ...] } ] } }
When enabled, CSS module changes also trigger JS reload. Pass as query parameter without value.
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');
Errors
Common errors & fixes
Error: Cannot find module 'css-hot-loader'
css-hot-loader not installed or not in devDependencies
fixnpm install css-hot-loader --save-dev
Module build failed: TypeError: The 'compilation' argument must be an instance of Compilation
Incompatible with Webpack 5; css-hot-loader v1.4.4 only supports Webpack 4 and below
fixUse Webpack 4 or consider alternative loaders like style-loader with HMR
HMR: hot reload did not trigger when CSS changed
Output CSS filename contains [contenthash] or dynamic hash, so the loader cannot find the CSS file to reload
fixUse a static filename in MiniCssExtractPlugin options: filename: 'bundle.css'
Uncaught Error: CSS hot loader: cannot get CSS file path for module
Incorrect fileMap option or CSS/JS entry name mismatch; the loader expects the CSS file to be named same as the JS module
fixEnsure CSS file path matches JS module name (e.g., src/foo.js -> dist/foo.css). Use fileMap option if needed
Audit
Dependencies
mini-css-extract-pluginrequiredRequired for CSS extraction; the plugin replaces extract-text-webpack-plugin for Webpack 4+