Registry / web-framework / webpack-hot-client

webpack-hot-client

JSON →
library4.2.0jsnpmunverified

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.

web-frameworkhttp-networkingdevops
npm install webpack-hot-client
github ↗package ↗
INSTALL
IMPORT
SIG · WEBPACK-HOT-CLIENT
W
webpack-hot-client
web-frameworkjavascriptv4.2.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

hotClient
✓ import hotClient from 'webpack-hot-client';
✗ const hotClient = require('webpack-hot-client');
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.
Client instance
✓ const client = hotClient(compiler, options);
The `hotClient` function is called with a webpack compiler instance and configuration options to initialize and return the HMR client instance.
Server event listener
✓ client.server.on('listening', () => { /* ... */ });
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).

This example demonstrates how to integrate webpack-hot-client with an Express server and webpack-dev-middleware, ensuring proper port allocation and HMR setup.

const hotClient = require('webpack-hot-client'); const middleware = require('webpack-dev-middleware'); const webpack = require('webpack'); const express = require('express'); const app = express(); const config = require('./webpack.config'); // Ensure this points to your webpack config const compiler = webpack(config); const { publicPath } = config.output; const options = { /* webpack-hot-client options, e.g., port: 8081 */ }; // We recommend calling the client _before_ adding the dev middleware const client = hotClient(compiler, options); const { server } = client; server.on('listening', () => { console.log(`webpack-hot-client server listening on port ${server.address().port}`); app.use(middleware(compiler, { publicPath })); // Serve static files if needed, e.g., for an index.html // app.use(express.static('public')); app.listen(3000, () => { console.log('Express server listening on port 3000'); }); });
Debug
Known issues
breakingThis 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.
fix
Ensure your project uses Webpack 4. If upgrading to Webpack 5+, consider alternatives or check for community forks/updates supporting newer Webpack versions.
affects: <=4.2.0
gotchaWebpack 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.
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.
affects: >=1.0.0
gotcha`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.
fix
Remove `new webpack.HotModuleReplacementPlugin()` from your `webpack.config.js` when `webpack-hot-client` is in use.
affects: >=1.0.0
gotchaWhen 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.
fix
Implement the `client.server.on('listening', () => { /* start middleware/compilation here */ });` pattern as shown in the quickstart example to ensure port availability.
affects: >=1.0.0
gotchaThe 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.
fix
Ensure your Node.js environment meets the specified engine requirements. Update Node.js to a supported LTS version if necessary.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Hot Module Replacement is not enabled.
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.
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).
WebSocket connection to 'ws://localhost:XXXX/sockjs-node' failed: Error during WebSocket handshake: Unexpected response code: 400
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.
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.
TypeError: Cannot read properties of undefined (reading 'on') at client.server.on
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.
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.
Upgrade
Version history
4.2.0latest on npm
Audit
Dependencies
webpackrequiredCore build tool it integrates with; defined as a peer dependency.
Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
1
Resources
githubhttps://github.com/shellscape/webpack-hot-client ↗
packagehttps://www.npmjs.com/package/webpack-hot-client ↗