Skip to content

Commit 0696c6a

Browse files
bjohansebasbjohansebas
committed
docs: add HMR notes and troubleshooting section (#2362)
* docs: add HMR notes and troubleshooting section Covers the recurring questions from the webpack-hot-middleware backlog: browser connection limits and HTTP/2 (webpack/webpack-hot-middleware#423, webpack/webpack-hot-middleware#298), warning filtering layers (webpack/webpack-hot-middleware#319, webpack/webpack-hot-middleware#228), absolute paths and public paths (webpack/webpack-hot-middleware#281, webpack/webpack-hot-middleware#203, webpack/webpack-hot-middleware#193), and a custom-events recipe (webpack/webpack-hot-middleware#118, webpack/webpack-hot-middleware#226). The client `reload` option now also notes its default differs from webpack-hot-middleware (webpack/webpack-hot-middleware#370). * fixup!
1 parent ea8362a commit 0696c6a

1 file changed

Lines changed: 52 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -387,7 +387,7 @@ entry: [
387387
| `path` | `string` | `/__webpack_hmr` | Path the SSE endpoint is served at. Must match the server `hot.path`. |
388388
| `timeout` | `number` | `20000` | Reconnection / heartbeat watchdog timeout in milliseconds. |
389389
| `overlay` | `boolean\|Object` | `true` | In-page overlay for problems. Same value shape as webpack-dev-server's [`client.overlay`](https://webpack.js.org/configuration/dev-server/#overlay): a boolean, or a JSON object with `errors`, `warnings`, `runtimeErrors` (booleans or filter functions) and `trustedTypesPolicyName`. Partial objects are filled with `true`. Also accepts the webpack-dev-middleware extensions `styles` (CSS overrides for the overlay card), `ansiColors` (ANSI → HTML color map) and `openEditorEndpoint` (when set, file references become clickable and issue `GET <endpoint>?fileName=<file:line:column>`), `paginate` (show one problem at a time with prev/next navigation, enabled by default — disable with `{"paginate":false}`; the endpoint is provided by your server, e.g. a route calling [launch-editor](https://github.com/yyx990803/launch-editor)). |
390-
| `reload` | `boolean` | `true` | Fall back to a full page reload when an update cannot be applied through HMR (e.g. recovering from a broken build). Set to `false` to keep HMR-only. |
390+
| `reload` | `boolean` | `true` | Fall back to a full page reload when an update cannot be applied through HMR (e.g. recovering from a broken build). Enabled by default, unlike webpack-hot-middleware; set to `false` to keep HMR-only. |
391391
| `logging` | `string` | `"info"` | Logger level — one of `"none"`, `"error"`, `"warn"`, `"info"`, `"log"`, `"verbose"`. Uses webpack's runtime logger. |
392392
| `name` | `string` | `""` | Restrict updates to a specific compilation name (useful with multi-compiler). |
393393
| `autoConnect` | `boolean` | `true` | Connect on load; set to `false` and call `setOptionsAndConnect()` manually. |
@@ -459,6 +459,57 @@ show("Rebuilding… 42%", 42); // progress ring
459459
hide();
460460
```
461461

462+
## HMR notes and troubleshooting
463+
464+
### Browser connection limits (many tabs)
465+
466+
Each open tab keeps one SSE connection to the `hot.path` endpoint. Over
467+
HTTP/1.1, browsers allow only ~6 concurrent connections per origin, so opening
468+
many tabs can leave the extra ones hanging (browsers have marked this
469+
[Won't Fix](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)).
470+
Multiple webpack entries on the same page already share a single connection,
471+
and the endpoint works over HTTP/2 out of the box — serve your development
472+
server over HTTP/2 if you need many simultaneous tabs.
473+
474+
### Filtering warnings
475+
476+
Three layers, from build to presentation:
477+
478+
- webpack's [`ignoreWarnings`](https://webpack.js.org/configuration/other-options/#ignorewarnings) removes them from the stats, so clients never receive them.
479+
- `hot: { statsOptions: { warnings: false } }` keeps them in the build output but out of the SSE payload.
480+
- On the client, `?overlay={"warnings":false}` hides them from the overlay and `?logging=error` from the console.
481+
482+
### Paths and public paths
483+
484+
- The client `path` option accepts absolute URLs (the endpoint sends
485+
`Access-Control-Allow-Origin: *`), which allows connecting across ports or
486+
hosts. Pages served over HTTPS need the endpoint over HTTPS too.
487+
- For apps with nested routes (`/some/route`), use an absolute
488+
`output.publicPath` (e.g. `"/"`): with a relative one the browser resolves
489+
`*.hot-update.json` requests against the current route and they 404.
490+
491+
### Custom events
492+
493+
The server can broadcast arbitrary payloads and the client can react to them —
494+
for example, forcing every open tab to reload on demand:
495+
496+
```js
497+
// Server
498+
const instance = middleware(compiler, { hot: true });
499+
instance.context.hot.publish({ action: "reload-all" });
500+
```
501+
502+
```js
503+
// Client
504+
const hotClient = require("webpack-dev-middleware/client");
505+
506+
hotClient.subscribe((payload) => {
507+
if (payload.action === "reload-all") {
508+
globalThis.location.reload();
509+
}
510+
});
511+
```
512+
462513
## API
463514

464515
`webpack-dev-middleware` also provides convenience methods that can be use to

0 commit comments

Comments
 (0)