feat: add browser client runtime for HMR (#2323)

* feat: add browser client runtime for HMR

Ports the browser client into `client-src/`, mirroring the layout used
in `webpack-dev-server` (source in `client-src/`, built to `client/`).

The client connects to the SSE endpoint via `EventSource`, parses
query-string options from `__resourceQuery`, dispatches `building`,
`built` and `sync` payloads, applies HMR through `process-update.js`
and renders compile-time errors and warnings through an in-page overlay
(`overlay.js`).

Exposed via the `./client` subpath export so users can wire it as a
webpack entry: `require('webpack-dev-middleware/client')`. The source
is transpiled with a browser-targeted babel override and the resulting
files are shipped under `/client`.

* test: add browser client runtime tests

Covers the public client API and key SSE handling paths in jsdom:
EventSource connection on default and custom paths, ignored heartbeat
messages, dispatch of building/built/sync to subscribers, custom
handler for unknown actions, warnings on invalid JSON, EventSource
wrapper caching across multiple entries, and timeout-driven reconnect.

* test: expand browser client coverage to mirror webpack-hot-middleware

Adds tests covering the original webpack-hot-middleware client suite
(processUpdate invocations on built/sync, errored/warning behavior,
overlay show/hide transitions, the overlayWarnings option, the name
filter), while keeping the new coverage for heartbeat handling,
invalid JSON warnings, EventSource wrapper caching across entries and
timeout-driven reconnects.

* ci: run on push and PRs against the hot-middleware umbrella branch

* refactor(client): switch process-update to promise-only HMR API

The ported logic called `module.hot.check`/`apply` with both a callback
and a Promise-handling branch to support webpack < 2. In webpack 5 both
paths fire, so the callback ran twice, triggering a redundant
`module.hot.apply` on every update.

Drop the legacy callback path and use the Promise API exclusively, which
is the canonical webpack 5 contract and matches our peer dependency.

* chore(client): type-check client-src with a dedicated tsconfig

Mirrors the layout webpack-dev-server uses: a separate
`tsconfig.client.json` (`noEmit`, browser-targeted libs,
`webpack/module` augmentation) runs over `client-src/` via a new
`lint:types-client` script, with a small `client-src/globals.d.ts`
declaring `ansi-html-community` and the per-page singletons the client
stores on `window`.

Refines the JSDoc annotations in `client-src/index.js` and
`client-src/process-update.js` so `module.hot`, `window` extensions
and the HMR `ApplyOptions` type-check cleanly.

* docs: document the browser client runtime in README

Adds a 'Hot Module Replacement client' section explaining how to wire
`webpack-dev-middleware/client` as a webpack entry, the query-string
options that the runtime understands, and the programmatic
`subscribe` / `subscribeAll` / `useCustomOverlay` /
`setOptionsAndConnect` exports.

* chore(client): adopt browser-outdated-recommended-commonjs eslint preset

Switches the client-src lint config to the dedicated preset
`eslint-config-webpack` ships for browser-targeted CommonJS code, the
same family of preset webpack-dev-server uses for its own client.

Brings the per-directory rule overrides down to two:
`no-console` (legitimately used for HMR status messages) and
`no-use-before-define` (relaxed for hoisted function declarations).

Adjusts the source to satisfy the rest of the preset directly: adds
`use strict` headers, fills in JSDoc for every function, renames
`EventSourceWrapper` to `createEventSourceWrapper` (per `new-cap`),
names the anonymous module exports, and reorders `performReload`
before `handleError` so it is declared before use.

* refactor(client): route logging through webpack's runtime logger

Wraps `webpack/lib/logging/runtime` in a small `utils/log.js` module
that exposes a level-based logger registered under the
`webpack-dev-middleware` name (matching the infrastructure logger the
server side already uses). Replaces every `console.log`/
`console.warn` call in the client and HMR update path with the
equivalent `log.info`/`log.warn`/`log.error` calls so output is
prefixed and gated by a single `logging` level.

User-facing API:

- `logging` query-string option accepts `none|error|warn|info|log|verbose`
- The previous `log`, `warn`, `noInfo` and `quiet` flags are dropped
  in favour of `logging`

Other cleanups enabled by this:

- Drop the `no-console: off` exception from the client-src ESLint config
- Update README's client option table accordingly
- Add tests covering the new `logging` levels and the logger prefix

* test(client): use snapshots for logger output assertions

Replaces regex-based `some(([msg]) => /.../).toBe(true)` checks on the
mocked console with `toMatchSnapshot()` over `mock.calls`. The
snapshots capture the exact log lines including the
`[webpack-dev-middleware]` prefix and per-call argument count, so any
change to the log format surfaces in the test output instead of silently
passing.

Adds explicit assertions to the existing error / warning flow tests so
`console.error` / `console.warn` mocks are not only silenced but also
verified to be called with the expected output.

* chore: document why client-src needs the ecmaVersion override

`eslint-config-webpack@4.9.6` still ships `browser-outdated-recommended-commonjs`
with `configs["javascript/es5"]` and no parser override, so `const`
is rejected. The module variant of the same preset patches this
upstream — we replicate the patch locally until the commonjs variant
does the same.

* refactor(client): migrate to ES modules and update Babel configuration

* fixup!

Author: bjohansebas

.github/workflows/nodejs.yml

@@ -5,10 +5,12 @@ on:
     branches:
       - main
       - next
+      - hot-middleware
   pull_request:
     branches:
       - main
       - next
+      - hot-middleware
 
 permissions:
   contents: read

.gitignore

@@ -6,6 +6,7 @@ logs
 npm-debug.log*
 .eslintcache
 .cspellcache
+/client
 /dist
 /local
 /reports

README.md

@@ -312,6 +312,77 @@ middleware(compiler, {
 });
 ```
 
+## Hot Module Replacement client
+
+When the server is configured to serve the hot module replacement endpoint, the bundled application needs a small runtime that subscribes to that stream and applies the updates. `webpack-dev-middleware` ships that runtime under the `./client` subpath. Add it as a webpack entry next to your application code and enable `HotModuleReplacementPlugin`:
+
+```js
+const webpack = require("webpack");
+
+module.exports = {
+  entry: ["webpack-dev-middleware/client", "./src/app.js"],
+  plugins: [new webpack.HotModuleReplacementPlugin()],
+};
+```
+
+The runtime connects to `/__webpack_hmr` by default. Any of the options below can be set by adding a query string to the entry path:
+
+```js
+entry: [
+  "webpack-dev-middleware/client?reload=true&overlay=false",
+  "./src/app.js",
+];
+```
+
+### Client options
+
+|        Name         |   Type    |     Default      | Description                                                                                                         |
+| :-----------------: | :-------: | :--------------: | :------------------------------------------------------------------------------------------------------------------ |
+|       `path`        | `string`  | `/__webpack_hmr` | Path the SSE endpoint is served at. Must match the server `hot.path`.                                               |
+|      `timeout`      | `number`  |     `20000`      | Reconnection / heartbeat watchdog timeout in milliseconds.                                                          |
+|      `overlay`      | `boolean` |      `true`      | Show compile-time errors in an in-page overlay.                                                                     |
+|  `overlayWarnings`  | `boolean` |     `false`      | Also show compile-time warnings in the overlay.                                                                     |
+|   `overlayStyles`   | `Object`  |       `{}`       | JSON object of CSS overrides for the overlay container. Pass JSON-encoded value via query string.                   |
+|    `ansiColors`     | `Object`  |       `{}`       | JSON object overriding the ANSI → HTML color map used by the overlay.                                               |
+|      `reload`       | `boolean` |     `false`      | Reload the page when an update cannot be applied through HMR.                                                       |
+|      `logging`      | `string`  |     `"info"`     | Logger level — one of `"none"`, `"error"`, `"warn"`, `"info"`, `"log"`, `"verbose"`. Uses webpack's runtime logger. |
+|       `name`        | `string`  |       `""`       | Restrict updates to a specific compilation name (useful with multi-compiler).                                       |
+|    `autoConnect`    | `boolean` |      `true`      | Connect on load; set to `false` and call `setOptionsAndConnect()` manually.                                         |
+| `dynamicPublicPath` | `boolean` |     `false`      | Prefix `path` with `__webpack_public_path__` at runtime.                                                            |
+
+### Programmatic API
+
+`webpack-dev-middleware/client` also exports a few functions for advanced cases:
+
+```js
+const hotClient = require("webpack-dev-middleware/client");
+
+// Receive every HMR payload (building / built / sync / custom).
+hotClient.subscribeAll((payload) => {
+  console.log("hot event", payload);
+});
+
+// Receive payloads whose `action` is not recognised by the client (i.e. custom
+// payloads published via the server's `instance.context.hot.publish(...)`).
+hotClient.subscribe((payload) => {
+  // do something
+});
+
+// Replace the default error overlay with your own implementation.
+hotClient.useCustomOverlay({
+  showProblems(type, lines) {
+    /* ... */
+  },
+  clear() {
+    /* ... */
+  },
+});
+
+// Connect manually when `autoConnect=false`. Accepts the same option keys as
+// the query-string API above.
+hotClient.setOptionsAndConnect({ path: "/__hmr" });
+```
+
 ## API
 
 `webpack-dev-middleware` also provides convenience methods that can be use to

babel.config.js

@@ -1,19 +1,33 @@
-const MIN_BABEL_VERSION = 7;
-
 module.exports = (api) => {
-  api.assertVersion(MIN_BABEL_VERSION);
   api.cache(true);
 
   return {
     presets: [
       [
         "@babel/preset-env",
         {
+          modules: false,
           targets: {
-            node: "20.9.0",
+            esmodules: true,
+            node: "0.12",
           },
         },
       ],
     ],
+    env: {
+      test: {
+        presets: [
+          [
+            "@babel/preset-env",
+            {
+              targets: {
+                node: "18.12.0",
+              },
+            },
+          ],
+        ],
+        plugins: ["@babel/plugin-transform-runtime"],
+      },
+    },
   };
 };

client-src/globals.d.ts

@@ -0,0 +1,28 @@
+/* eslint-disable */
+
+declare module "ansi-html-community" {
+  function ansiHtmlCommunity(str: string): string;
+  namespace ansiHtmlCommunity {
+    function setColors(colors: Record<string, string | string[]>): void;
+  }
+  export = ansiHtmlCommunity;
+}
+
+interface ClientReporter {
+  cleanProblemsCache(): void;
+  problems(
+    type: "errors" | "warnings",
+    obj: { errors: string[]; warnings: string[]; name?: string },
+  ): boolean;
+  success(): void;
+  useCustomOverlay(customOverlay: unknown): void;
+}
+
+interface EventSourceWrapper {
+  addMessageListener(fn: (event: { data: string }) => void): void;
+}
+
+interface Window {
+  __wdmEventSourceWrapper?: Record<string, EventSourceWrapper>;
+  __webpack_dev_middleware_hot_reporter__?: ClientReporter;
+}