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.
webpackHotMiddleware
✓ const webpackHotMiddleware = require('webpack-hot-middleware');
✗ import webpackHotMiddleware from 'webpack-hot-middleware';
// or
import { webpackHotMiddleware } from 'webpack-hot-middleware';
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.
'webpack-hot-middleware/client'
✓ entry: { main: ['webpack-hot-middleware/client', './src/main.js'] }
✗ entry: { main: ['./src/main.js', 'webpack-hot-middleware/client'] }
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.
HotModuleReplacementPlugin
✓ new webpack.HotModuleReplacementPlugin()
✗ new HotModuleReplacementPlugin()
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.
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.
/* webpack.config.js */
const webpack = require('webpack');
const path = require('path');
module.exports = {
mode: 'development',
entry: {
main: ['webpack-hot-middleware/client?path=/__webpack_hmr&timeout=20000', './src/main.js'],
},
output: {
filename: '[name].bundle.js',
path: path.resolve(__dirname, 'dist'),
publicPath: '/',
},
plugins: [
new webpack.HotModuleReplacementPlugin(),
// new webpack.NoEmitOnErrorsPlugin() // Optional: Uncomment for cleaner error handling, but may hide issues
],
module: {
rules: [
{
test: /\.js$/,
exclude: /node_modules/,
use: {
loader: 'babel-loader',
options: { presets: ['@babel/preset-env'] }
}
}
]
}
};
/* server.js */
const express = require('express');
const webpack = require('webpack');
const webpackDevMiddleware = require('webpack-dev-middleware');
const webpackHotMiddleware = require('webpack-hot-middleware');
const webpackConfig = require('./webpack.config');
const app = express();
const compiler = webpack(webpackConfig);
app.use(webpackDevMiddleware(compiler, {
publicPath: webpackConfig.output.publicPath,
stats: { colors: true },
}));
app.use(webpackHotMiddleware(compiler, {
log: console.log,
path: '/__webpack_hmr',
heartbeat: 10 * 1000,
}));
app.get('/', (req, res) => {
res.send(`
<!DOCTYPE html>
<html>
<head><title>Webpack Hot Middleware</title></head>
<body>
<h1>Hello Webpack Hot Middleware!</h1>
<div id="root"></div>
<script src="/main.bundle.js"></script>
</body>
</html>
`);
});
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Server listening on port ${PORT}`);
});
/* src/main.js */
import './styles.css'; // Assume you have a simple css file
console.log('App started!');
const root = document.getElementById('root');
let count = 0;
function render() {
root.innerHTML = `Count: ${count++}`;
}
render();
if (module.hot) {
module.hot.accept('./main.js', function() {
console.log('Accepting updated main.js!');
render();
});
module.hot.accept('./styles.css', function() {
console.log('Accepting updated styles.css!');
});
}
Errors
Common errors & fixes
Hot Module Replacement is disabled.
The `webpack.HotModuleReplacementPlugin` was not added to the webpack configuration's `plugins` array.
fixAdd `new webpack.HotModuleReplacementPlugin()` to your `webpack.config.js`.
Module not found: Error: Can't resolve 'webpack-hot-middleware/client'
The `webpack-hot-middleware/client` entry point string is incorrect or misspelled in your webpack configuration.
fixVerify the entry string `webpack-hot-middleware/client` (including the exact casing) in your `webpack.config.js`.
WebSocket connection to 'ws://localhost:3000/__webpack_hmr' failed: Error during WebSocket handshake: Unexpected response code: 404 (or similar connection errors in browser console)
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.
fixEnsure `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`. compiler.plugin is not a function (or similar errors related to compiler hooks)
`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.
fixEnsure `webpack-hot-middleware` is updated to a version compatible with your installed Webpack version (e.g., v2.25.3+ for better Webpack 5 compatibility).
Audit
Dependencies
webpackrequiredRequired for compilation and to provide the HotModuleReplacementPlugin.
webpack-dev-middlewarerequiredThis package is designed to work as an extension to webpack-dev-middleware, providing the server-side assets and handling file watching.