webpack-hot-client

Common errors

• Error: Hot Module Replacement is not enabled.

  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.
  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

  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.
  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

  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.
  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.

Warnings

• breaking 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.
  Fix: Ensure your project uses Webpack 4. If upgrading to Webpack 5+, consider alternatives or check for community forks/updates supporting newer Webpack versions.
• gotcha 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.
  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.
• 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.
• gotcha 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.
  Fix: Implement the `client.server.on('listening', () => { /* start middleware/compilation here */ });` pattern as shown in the quickstart example to ensure port availability.
• gotcha 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.
  Fix: Ensure your Node.js environment meets the specified engine requirements. Update Node.js to a supported LTS version if necessary.

Install

• npm install webpack-hot-client npm
• yarn add webpack-hot-client yarn
• pnpm add webpack-hot-client pnpm

Imports

• hotClient
  wrong:

  const hotClient = require('webpack-hot-client');

  correct:

  import hotClient from '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).

Quickstart

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');
  });
});