{"id":12664,"library":"webpack-hot-middleware","title":"Webpack Hot Middleware","description":"Webpack Hot Middleware provides hot module replacement (HMR) capabilities for Webpack applications by integrating with an existing server, such as Express, and `webpack-dev-middleware`. This library is a direct alternative to `webpack-dev-server` for scenarios where developers need more control over their server setup, particularly for integrating HMR into custom backend environments. It focuses exclusively on the client-server communication mechanism for HMR updates, subscribing to server-side changes and executing them using Webpack's native HMR API. The current stable version is 2.26.1, released in February 2024, indicating a steady but infrequent release cadence primarily for bug fixes and compatibility updates. It does not handle the actual component-level hot reloading, leaving that to other libraries like React Hot Loader.","status":"active","version":"2.26.1","language":"javascript","source_language":"en","source_url":"https://github.com/webpack-contrib/webpack-hot-middleware","tags":["javascript","webpack","hmr","hot","module","reloading","hot-reloading","middleware","express"],"install":[{"cmd":"npm install webpack-hot-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add webpack-hot-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add webpack-hot-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for compilation and to provide the HotModuleReplacementPlugin.","package":"webpack","optional":false},{"reason":"This package is designed to work as an extension to webpack-dev-middleware, providing the server-side assets and handling file watching.","package":"webpack-dev-middleware","optional":false}],"imports":[{"note":"This module is typically imported using CommonJS `require()` in Node.js server environments. While Webpack supports ESM, the middleware itself and its primary usage examples lean towards CommonJS for server-side integration.","wrong":"import webpackHotMiddleware from 'webpack-hot-middleware';\n// or\nimport { webpackHotMiddleware } from 'webpack-hot-middleware';","symbol":"webpackHotMiddleware","correct":"const webpackHotMiddleware = require('webpack-hot-middleware');"},{"note":"This is a client-side script that must be added as an entry point to your webpack configuration. It should generally be the *first* entry in a bundle to ensure the HMR client loads and initializes before other application code. It's a string path, not a direct `import` statement in source code.","wrong":"entry: { main: ['./src/main.js', 'webpack-hot-middleware/client'] }","symbol":"'webpack-hot-middleware/client'","correct":"entry: { main: ['webpack-hot-middleware/client', './src/main.js'] }"},{"note":"This plugin, provided by Webpack itself, is essential for enabling Webpack's native HMR capabilities, which `webpack-hot-middleware` then orchestrates. It must be instantiated from the `webpack` object.","wrong":"new HotModuleReplacementPlugin()","symbol":"HotModuleReplacementPlugin","correct":"new webpack.HotModuleReplacementPlugin()"}],"quickstart":{"code":"/* webpack.config.js */\nconst webpack = require('webpack');\nconst path = require('path');\n\nmodule.exports = {\n  mode: 'development',\n  entry: {\n    main: ['webpack-hot-middleware/client?path=/__webpack_hmr&timeout=20000', './src/main.js'],\n  },\n  output: {\n    filename: '[name].bundle.js',\n    path: path.resolve(__dirname, 'dist'),\n    publicPath: '/',\n  },\n  plugins: [\n    new webpack.HotModuleReplacementPlugin(),\n    // new webpack.NoEmitOnErrorsPlugin() // Optional: Uncomment for cleaner error handling, but may hide issues\n  ],\n  module: {\n    rules: [\n      {\n        test: /\\.js$/,\n        exclude: /node_modules/,\n        use: {\n          loader: 'babel-loader',\n          options: { presets: ['@babel/preset-env'] }\n        }\n      }\n    ]\n  }\n};\n\n/* server.js */\nconst express = require('express');\nconst webpack = require('webpack');\nconst webpackDevMiddleware = require('webpack-dev-middleware');\nconst webpackHotMiddleware = require('webpack-hot-middleware');\nconst webpackConfig = require('./webpack.config');\n\nconst app = express();\nconst compiler = webpack(webpackConfig);\n\napp.use(webpackDevMiddleware(compiler, {\n  publicPath: webpackConfig.output.publicPath,\n  stats: { colors: true },\n}));\n\napp.use(webpackHotMiddleware(compiler, {\n  log: console.log,\n  path: '/__webpack_hmr',\n  heartbeat: 10 * 1000,\n}));\n\napp.get('/', (req, res) => {\n  res.send(`\n    <!DOCTYPE html>\n    <html>\n    <head><title>Webpack Hot Middleware</title></head>\n    <body>\n      <h1>Hello Webpack Hot Middleware!</h1>\n      <div id=\"root\"></div>\n      <script src=\"/main.bundle.js\"></script>\n    </body>\n    </html>\n  `);\n});\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n  console.log(`Server listening on port ${PORT}`);\n});\n\n/* src/main.js */\nimport './styles.css'; // Assume you have a simple css file\n\nconsole.log('App started!');\n\nconst root = document.getElementById('root');\nlet count = 0;\nfunction render() {\n  root.innerHTML = `Count: ${count++}`;\n}\n\nrender();\n\nif (module.hot) {\n  module.hot.accept('./main.js', function() {\n    console.log('Accepting updated main.js!');\n    render();\n  });\n  module.hot.accept('./styles.css', function() {\n    console.log('Accepting updated styles.css!');\n  });\n}","lang":"javascript","description":"This quickstart demonstrates how to set up `webpack-hot-middleware` with Express and `webpack-dev-middleware`. It includes a basic Webpack configuration, an Express server, and a client-side entry point (`src/main.js`) with simple HMR acceptance logic."},"warnings":[{"fix":"Remove `webpack/hot/dev-server` or `webpack/hot/only-dev-server` from your webpack `entry` configuration. Instead, add `'webpack-hot-middleware/client'` as the first entry for your bundles.","message":"As of version 2.0.0, all client functionality was rolled directly into `webpack-hot-middleware`. You must remove any references to `webpack/hot/dev-server` or `webpack/hot/only-dev-server` from your webpack configuration's entry array.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure both `webpack-dev-middleware` and `webpack-hot-middleware` are installed and used in your server setup, with `webpack-dev-middleware` being applied first.","message":"`webpack-hot-middleware` requires `webpack-dev-middleware` to be installed and correctly configured to serve the webpack-compiled assets. It works in conjunction with `webpack-dev-middleware`, not as a standalone solution for asset serving.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `new webpack.HotModuleReplacementPlugin()` to the `plugins` array in your `webpack.config.js`.","message":"The `webpack.HotModuleReplacementPlugin` must be included in your webpack configuration's `plugins` array for Hot Module Replacement to function. Without this plugin, `webpack-hot-middleware` will not be able to enable HMR.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Place `'webpack-hot-middleware/client'` at the beginning of each relevant entry point array in your `webpack.config.js`.","message":"For correct HMR client behavior, the `'webpack-hot-middleware/client'` entry should generally be the *first* item in your `entry` array for each bundle. This ensures the HMR client loads before application code, allowing it to correctly intercept and handle updates.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `['webpack-hot-middleware/client', './your-entry.js']` is applied to all desired entry points.","message":"When using multiple Webpack entry points, `webpack-hot-middleware/client` must be included in *each* entry point that you want to enable hot reloading for. Omitting it from an entry point will prevent HMR for that specific bundle.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement `module.hot.accept()` in your client-side modules to define how they should react to updates, or use frameworks/loaders with built-in HMR integration.","message":"To correctly apply HMR updates to your application code (e.g., React components, style sheets), you must explicitly use Webpack's HMR API (`module.hot.accept()`) in your client-side code, or use a loader/plugin that does so automatically (like `react-hot-loader` or `style-loader`). `webpack-hot-middleware` only provides the transport layer.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `new webpack.HotModuleReplacementPlugin()` to your `webpack.config.js`.","cause":"The `webpack.HotModuleReplacementPlugin` was not added to the webpack configuration's `plugins` array.","error":"Hot Module Replacement is disabled."},{"fix":"Verify the entry string `webpack-hot-middleware/client` (including the exact casing) in your `webpack.config.js`.","cause":"The `webpack-hot-middleware/client` entry point string is incorrect or misspelled in your webpack configuration.","error":"Module not found: Error: Can't resolve 'webpack-hot-middleware/client'"},{"fix":"Ensure `app.use(webpackHotMiddleware(compiler, { path: '/__webpack_hmr' }));` is correctly set up on your server and that the client entry also specifies the same path: `webpack-hot-middleware/client?path=/__webpack_hmr`.","cause":"The `webpack-hot-middleware` is not correctly mounted on your server, or the `path` configuration option (both server-side and client-side via query string) does not match.","error":"WebSocket connection to 'ws://localhost:3000/__webpack_hmr' failed: Error during WebSocket handshake: Unexpected response code: 404 (or similar connection errors in browser console)"},{"fix":"Ensure `webpack-hot-middleware` is updated to a version compatible with your installed Webpack version (e.g., v2.25.3+ for better Webpack 5 compatibility).","cause":"`webpack-hot-middleware` might be using deprecated Webpack compiler hooks in an older version, or you're using a version incompatible with your Webpack major version.","error":"compiler.plugin is not a function (or similar errors related to compiler hooks)"}],"ecosystem":"npm"}