{"id":19428,"library":"css-hot-loader","title":"CSS Hot Loader","description":"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.","status":"maintenance","version":"1.4.4","language":"javascript","source_language":"en","source_url":"git://github.com/shepherdwind/css-hot-loader","tags":["javascript"],"install":[{"cmd":"npm install css-hot-loader","lang":"bash","label":"npm"},{"cmd":"yarn add css-hot-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add css-hot-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for CSS extraction; the plugin replaces extract-text-webpack-plugin for Webpack 4+","package":"mini-css-extract-plugin","optional":false}],"imports":[{"note":"Loader is used as a string reference in Webpack config, not imported in JS files. Must be placed before MiniCssExtractPlugin.loader.","symbol":"css-hot-loader","correct":"module.exports = { module: { rules: [ { test: /\\.css$/, use: ['css-hot-loader', MiniCssExtractPlugin.loader, 'css-loader'] } ] } }"},{"note":"Options are passed as query string on the loader string; using options object syntax is not supported.","wrong":"config: { module: { rules: [ { use: ['css-hot-loader', { loader: 'css-hot-loader', options: { fileMap: '../css/{fileName}' } }, ...] } ] } }","symbol":"fileMap option","correct":"config: { module: { rules: [ { use: ['css-hot-loader?fileMap=../css/{fileName}', ...] } ] } }"},{"note":"reloadAll is a Boolean flag, enabled by adding the query parameter without a value.","wrong":"config: { module: { rules: [ { use: ['css-hot-loader', { reloadAll: true }, ...] } ] } }","symbol":"reloadAll option","correct":"config: { module: { rules: [ { use: ['css-hot-loader?reloadAll', ...] } ] } }"},{"note":"When enabled, CSS module changes also trigger JS reload. Pass as query parameter without value.","wrong":"config: { module: { rules: [ { use: ['css-hot-loader', { cssModule: true }, ...] } ] } }","symbol":"cssModule option","correct":"config: { module: { rules: [ { use: ['css-hot-loader?cssModule', ...] } ] } }"}],"quickstart":{"code":"// webpack.config.js\nconst MiniCssExtractPlugin = require('mini-css-extract-plugin');\n\nmodule.exports = {\n  mode: 'development',\n  entry: './src/index.js',\n  output: {\n    filename: 'bundle.js',\n    path: __dirname + '/dist'\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.css$/,\n        use: [\n          'css-hot-loader',\n          MiniCssExtractPlugin.loader,\n          'css-loader'\n        ]\n      }\n    ]\n  },\n  plugins: [\n    new MiniCssExtractPlugin({\n      filename: 'bundle.css'\n    })\n  ]\n};\n\n// src/index.js\nimport './style.css';\nconsole.log('CSS HMR with extracted file');","lang":"javascript","description":"Webpack config example using css-hot-loader with mini-css-extract-plugin for HMR on extracted CSS"},"warnings":[{"fix":"Use a static filename like 'bundle.css' or '[name].css' without [contenthash] or [chunkhash]","message":"Output CSS filename must be static; contenthash in filename breaks HMR","severity":"breaking","affected_versions":"=1.4.4"},{"fix":"Ensure loader order: ['css-hot-loader', MiniCssExtractPlugin.loader, 'css-loader']","message":"css-hot-loader must be placed before MiniCssExtractPlugin.loader in the use array; otherwise HMR won't work","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Use string syntax: 'css-hot-loader?reloadAll' instead of { loader: 'css-hot-loader', options: { reloadAll: true } }","message":"Options must be passed as query string on the loader name, not via options object","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Only enable cssModule if you need JS to re-execute on CSS change; otherwise omit the option","message":"When using CSS Modules (cssModule option), JS files will also reload on CSS changes, potentially causing full page refresh","severity":"gotcha","affected_versions":">=1.1"},{"fix":"Replace extract-text-webpack-plugin with mini-css-extract-plugin and update loader config accordingly","message":"extract-text-webpack-plugin usage is deprecated; switch to mini-css-extract-plugin for Webpack 4+","severity":"deprecated","affected_versions":">=1.4"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"npm install css-hot-loader --save-dev","cause":"css-hot-loader not installed or not in devDependencies","error":"Error: Cannot find module 'css-hot-loader'"},{"fix":"Use Webpack 4 or consider alternative loaders like style-loader with HMR","cause":"Incompatible with Webpack 5; css-hot-loader v1.4.4 only supports Webpack 4 and below","error":"Module build failed: TypeError: The 'compilation' argument must be an instance of Compilation"},{"fix":"Use a static filename in MiniCssExtractPlugin options: filename: 'bundle.css'","cause":"Output CSS filename contains [contenthash] or dynamic hash, so the loader cannot find the CSS file to reload","error":"HMR: hot reload did not trigger when CSS changed"},{"fix":"Ensure CSS file path matches JS module name (e.g., src/foo.js -> dist/foo.css). Use fileMap option if needed","cause":"Incorrect fileMap option or CSS/JS entry name mismatch; the loader expects the CSS file to be named same as the JS module","error":"Uncaught Error: CSS hot loader: cannot get CSS file path for module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}