{"id":15932,"library":"webpack-hot-client","title":"webpack-hot-client","description":"webpack-hot-client is a versatile client for integrating webpack Hot Module Replacement (HMR) into existing server frameworks like Express or Koa, without the need for webpack-dev-server. It enables real-time module updates in the browser during development. The current stable version is 4.2.0, with a release cadence that prioritizes stability, maintenance, and dependency updates, as seen in recent patch releases like 4.1.2. Its key differentiators include automatically setting up a WebSocket server for client-server communication, injecting necessary client-side scripts, and configuring webpack with the appropriate HMR plugins and entries at runtime. This allows developers to leverage HMR while retaining full control over their server infrastructure, making it ideal for projects that use custom server setups.","status":"active","version":"4.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/shellscape/webpack-hot-client","tags":["javascript","webpack"],"install":[{"cmd":"npm install webpack-hot-client","lang":"bash","label":"npm"},{"cmd":"yarn add webpack-hot-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add webpack-hot-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core build tool it integrates with; defined as a peer dependency.","package":"webpack","optional":false}],"imports":[{"note":"The primary export is a default function. While `require` is shown in examples for Node.js environments (which align with the package's engine requirements), ESM `import` is the modern approach. For Node.js versions supporting ESM, this `import` syntax is preferred; otherwise, `require` is used.","wrong":"const hotClient = require('webpack-hot-client');","symbol":"hotClient","correct":"import hotClient from 'webpack-hot-client';"},{"note":"The `hotClient` function is called with a webpack compiler instance and configuration options to initialize and return the HMR client instance.","symbol":"Client instance","correct":"const client = hotClient(compiler, options);"},{"note":"The client exposes its underlying WebSocket server, allowing you to attach event listeners, such as waiting for the server to start listening before proceeding with other setup (e.g., webpack-dev-middleware).","symbol":"Server event listener","correct":"client.server.on('listening', () => { /* ... */ });"}],"quickstart":{"code":"const hotClient = require('webpack-hot-client');\nconst middleware = require('webpack-dev-middleware');\nconst webpack = require('webpack');\nconst express = require('express');\nconst app = express();\n\nconst config = require('./webpack.config'); // Ensure this points to your webpack config\nconst compiler = webpack(config);\nconst { publicPath } = config.output;\nconst options = { /* webpack-hot-client options, e.g., port: 8081 */ };\n\n// We recommend calling the client _before_ adding the dev middleware\nconst client = hotClient(compiler, options);\nconst { server } = client;\n\nserver.on('listening', () => {\n  console.log(`webpack-hot-client server listening on port ${server.address().port}`);\n  app.use(middleware(compiler, { publicPath }));\n\n  // Serve static files if needed, e.g., for an index.html\n  // app.use(express.static('public'));\n\n  app.listen(3000, () => {\n    console.log('Express server listening on port 3000');\n  });\n});\n","lang":"javascript","description":"This example demonstrates how to integrate webpack-hot-client with an Express server and webpack-dev-middleware, ensuring proper port allocation and HMR setup."},"warnings":[{"fix":"Ensure your project uses Webpack 4. If upgrading to Webpack 5+, consider alternatives or check for community forks/updates supporting newer Webpack versions.","message":"This module has a peer dependency on Webpack v4.0.0. It may not function correctly with Webpack 5+ without potential configuration adjustments or compatibility issues.","severity":"breaking","affected_versions":"<=4.2.0"},{"fix":"Modify your `webpack.config.js` to ensure the `entry` property adheres to the required array or object-of-arrays format, even for zero-config webpack v4+ setups.","message":"Webpack configuration's `entry` option must be an `Array` of `String` or an `Object` whose values are `Array`s of `String`. A `Function` is also valid if it returns one of these formats. Using other `entry` formats can lead to unexpected HMR behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Remove `new webpack.HotModuleReplacementPlugin()` from your `webpack.config.js` when `webpack-hot-client` is in use.","message":"`webpack-hot-client` automatically adds `HotModuleReplacementPlugin` and necessary entries to your webpack config at runtime. Manually including `HotModuleReplacementPlugin` in your webpack config while using this module can cause conflicts or 'wonky' results.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement the `client.server.on('listening', () => { /* start middleware/compilation here */ });` pattern as shown in the quickstart example to ensure port availability.","message":"When using the default `port` option value of `0` (which allocates a random available port), starting webpack compilation (or passing a compiler to `webpack-dev-middleware`) must occur *after* the socket server has finished listening and allocated its port. Otherwise, the build may not contain the correct HMR port.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js environment meets the specified engine requirements. Update Node.js to a supported LTS version if necessary.","message":"The module requires Node.js versions `>= 6.9.0 < 7.0.0 || >= 8.9.0`. Usage with Node.js 7.x or versions outside these specified ranges may lead to compatibility issues.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify that your webpack `entry` option is an array or object-of-arrays. Ensure you are not manually including `HotModuleReplacementPlugin` if `autoConfigure` is enabled (which it is by default). Check the order of operations if using a dynamic port (see warnings).","cause":"Webpack's Hot Module Replacement Plugin was not correctly applied, or the client-side HMR scripts were not injected into the build. This can happen if the `entry` configuration is incorrect or `autoConfigure` is disabled without manual setup.","error":"Error: Hot Module Replacement is not enabled."},{"fix":"Confirm the `webpack-hot-client` server is listening before webpack compilation starts (especially with `port: 0`). Ensure the `publicPath` in your webpack output configuration is correctly set. Check for other processes using the same port if a static port is configured.","cause":"The client-side HMR script is trying to connect to a WebSocket server that isn't running, or the port is incorrect, or another service is conflicting on the port. This often occurs when the `webpack-hot-client` server hasn't fully started, or the `publicPath` configured in webpack doesn't match the client's expectations for the WebSocket URL.","error":"WebSocket connection to 'ws://localhost:XXXX/sockjs-node' failed: Error during WebSocket handshake: Unexpected response code: 400"},{"fix":"Inspect the `compiler` and `options` passed to `hotClient` for validity. Ensure `webpack` and `webpack-hot-client` are correctly installed and imported. Verify your Node.js version is supported.","cause":"The `client` object returned by `hotClient` or its `server` property is undefined or null, usually because `hotClient` failed to initialize due to invalid compiler or options, or it was called in an environment where it cannot create a server.","error":"TypeError: Cannot read properties of undefined (reading 'on') at client.server.on"}],"ecosystem":"npm"}