Skip to content

Commit f35a596

Browse files
feat(hot): every browser option set in node or on the query, one name each (#2436)
* feat(hot): every browser option set in node or on the query `hot.client` and the injected entry's query were two overlapping option sets with a gap on each side. They are one set now. `hot`, `liveReload` and `urlPrefix` were readable from the query alone and can be set in node: middleware(compiler, { hot: { client: { hot: false, liveReload: true, urlPrefix: "my-server" } }, }) `transport`, `path` and `name` go the other way: the middleware set them and they could not be overridden, which left no way to point a client at an endpoint reached through a proxy or on another origin. They are defaults now — the resolved `hot.transport`, the resolved `hot.path` and the compilation's name — and `hot.client` is spread over them, so nothing changes for anyone not setting them. middleware(compiler, { hot: { client: { path: "wss://dev.example.com/__webpack_hmr" } }, }) A `hot.transport` of your own gets a client too when `hot.client.transport` says which of the two built-in protocols yours carries; without it the client is still yours to add. Overriding the transport without an endpoint of its own points the client back at this middleware speaking the wrong protocol, so that combination is warned about rather than left as a page that never connects. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01UjuMAuk9o6UazjHzcAQCTA * refactor(client): one name per browser option, no aliases The query had picked up two second spellings from webpack-dev-server — `webSocketURL` for `path` and `live-reload` for `liveReload` — and the page-url parameter was spelled `-live-reload` while the option it turns off is `liveReload`. Dropped all three: each option is one name, in `hot.client`, in the entry query and in the page parameters alike. dev-server maps its own spellings when it moves over. `?webpack-dev-middleware-live-reload=false` is now `?webpack-dev-middleware-liveReload=false`, still matched case-insensitively. None of this was released. Added a test that reads the names the client acts on out of `setOverrides` and the names `hot.client` accepts out of the schema, and fails unless the two lists are equal — an option with only one of the two spellings, or a second name for one setting, breaks it rather than going unnoticed. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01UjuMAuk9o6UazjHzcAQCTA --------- Co-authored-by: Claude Opus 5 <[email protected]>
1 parent 56535c8 commit f35a596

13 files changed

Lines changed: 635 additions & 87 deletions

‎.changeset/client-live-reload.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,21 @@
33
---
44

55
The client can now keep a page up to date without Hot Module Replacement. `hot`
6-
(default `true`) says whether a build is applied as an update, and `live-reload`
6+
(default `true`) says whether a build is applied as an update, and `liveReload`
77
(default `true`) reloads the page on a build that changed something when it is
88
not — so a project with no `HotModuleReplacementPlugin` still sees its changes.
99
A build that changed nothing is left alone either way.
1010

1111
Added a `reload` action, for a change no compilation knows about: publish
1212
`{ action: "reload" }` and every page loads itself again, whatever `hot` and
13-
`live-reload` are set to. It does what the `subscribe()` example in the README
13+
`liveReload` are set to. It does what the `subscribe()` example in the README
1414
used to have you write by hand.
1515

1616
Added `urlPrefix` (default `"webpack-dev-middleware"`), which names the page-url
17-
parameters that turn `hot` and `live-reload` off for a single page —
18-
`?webpack-dev-middleware-live-reload=false`.
17+
parameters that turn `hot` and `liveReload` off for a single page —
18+
`?webpack-dev-middleware-liveReload=false`.
1919

2020
`live-reload` used to be accepted as another spelling of `reload`. The two are
2121
different — `reload` is the fallback for an update that was tried and could not
22-
be applied — and `live-reload` now means what it says. It was never released
23-
under the old meaning.
22+
be applied — so the one that reloads on a build is its own option, `liveReload`.
23+
`live-reload` is not accepted under either meaning. It was never released.
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
"webpack-dev-middleware": minor
3+
---
4+
5+
every browser option can be set on the middleware as well as on the query
6+
7+
`hot.client` and the injected entry's query are now one option set rather than
8+
two overlapping ones. `hot`, `liveReload` and `urlPrefix` were readable from the
9+
query alone and can now be set in node:
10+
11+
```js
12+
app.use(
13+
middleware(compiler, {
14+
hot: { client: { hot: false, liveReload: true, urlPrefix: "my-server" } },
15+
}),
16+
);
17+
```
18+
19+
`transport`, `path` and `name` go the other way: they were the middleware's to
20+
set, and can now be overridden, which is what a page reaching the endpoint
21+
through a proxy or on another origin needs.
22+
23+
```js
24+
app.use(
25+
middleware(compiler, {
26+
hot: { client: { path: "wss://dev.example.com/__webpack_hmr" } },
27+
}),
28+
);
29+
```
30+
31+
The middleware's own values — the resolved `hot.transport`, the resolved
32+
`hot.path` and the compilation's name — remain the defaults, so nothing changes
33+
for anyone not setting them.
34+
35+
A `hot.transport` of your own now gets a client too, when `hot.client.transport`
36+
says which of the two built-in protocols yours carries. Without it the client is
37+
still yours to add, as before.
38+
39+
Every option has one name and no aliases, in `hot.client`, in the entry query
40+
and in the page-url parameters alike. The two second spellings the query had
41+
picked up from webpack-dev-server — `webSocketURL` for `path` and `live-reload`
42+
for `liveReload` — are gone, and so is the `-live-reload` page parameter, which
43+
is now `-liveReload`. Neither alias was ever released.

‎README.md‎

Lines changed: 45 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -541,7 +541,7 @@ Two things do change, and `hot.inject: false` turns both off:
541541

542542
One caveat: if the compiler was already watching before the middleware was created, the runtime appears from the next build onwards rather than the first one. Create the middleware before starting the watch to avoid it.
543543

544-
No client is added when [`hot.transport`](#hottransport) is a function either — the built-in one speaks Server-Sent Events and WebSocket, and a transport of your own carries whatever protocol you wrote it to carry, so the client that speaks it is yours to add. `HotModuleReplacementPlugin` is still applied for you. `hot.inject: false` silences the reminder, and turns that off as well — apply the plugin yourself if you use it.
544+
No client is added when [`hot.transport`](#hottransport) is a function either — the built-in one speaks Server-Sent Events and WebSocket, and a transport of your own carries whatever protocol you wrote it to carry, so the client that speaks it is yours to add unless [`hot.client.transport`](#client-options) says which of the two yours speaks. `HotModuleReplacementPlugin` is still applied for you. `hot.inject: false` silences the reminder, and turns that off as well — apply the plugin yourself if you use it.
545545

546546
The [client options](#client-options) below are set on the middleware, next to
547547
the rest of the hot configuration, and the injected entry carries them to the
@@ -555,9 +555,34 @@ app.use(
555555
);
556556
```
557557

558-
`transport`, `path` and `name` are not accepted there: the middleware knows all
559-
three already and sets them itself, so the runtime cannot be pointed somewhere
560-
the server is not listening.
558+
Every option below can be set either way, and they are the same options: what
559+
`hot.client` takes is what the query carries. `transport`, `path` and `name`
560+
differ only in having a value the middleware already knows — the resolved
561+
[`hot.transport`](#hottransport), the resolved [`hot.path`](#hotpath) and the
562+
compilation's own name — so setting one replaces that default rather than
563+
adding to it. That is what a page reaching the endpoint through a proxy or on
564+
another origin needs:
565+
566+
```js
567+
app.use(
568+
middleware(compiler, {
569+
hot: { client: { path: "wss://dev.example.com/__webpack_hmr" } },
570+
}),
571+
);
572+
```
573+
574+
A [`hot.transport`](#hottransport) of your own gets no client by default, since
575+
the built-in one speaks Server-Sent Events and WebSocket and cannot know what
576+
yours carries. If yours carries one of those two, say which and the client is
577+
added as usual:
578+
579+
```js
580+
app.use(
581+
middleware(compiler, {
582+
hot: { transport: myOwnStream, client: { transport: "sse" } },
583+
}),
584+
);
585+
```
561586

562587
The [`overlay` filters](#client-overlay-options) can be functions here as well.
563588
They travel to the browser as their own source, so write one as an arrow
@@ -600,17 +625,23 @@ as well.
600625

601626
### Client options
602627

628+
Each of these is set either on the middleware as `hot.client.<name>` or on the
629+
entry's query as `<name>=<value>`, with the same effect. Each has one name and
630+
no aliases, in both places and in the page-url parameters below. `transport`, `path`
631+
and `name` default to what the middleware resolved rather than to the value in
632+
the table, which is what they are when nothing else is serving them.
633+
603634
| Name | Type | Default | Description |
604635
| :-----------------: | :---------------: | :------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
605-
| `transport` | `string` | `"sse"` | How the events are carried: `"sse"` or `"ws"`. Must match the server [`hot.transport`](#hottransport). |
606-
| `path` | `string` | `/__webpack_hmr` | Path the endpoint is served at. Must match the server `hot.path`. |
636+
| `transport` | `string` | `"sse"` | How the events are carried: `"sse"` or `"ws"`. Defaults to the server [`hot.transport`](#hottransport); override it only together with `path`, since a client asking this endpoint for a protocol it does not serve never connects — the middleware warns when it sees that. |
637+
| `path` | `string` | `/__webpack_hmr` | Where the runtime connects. Defaults to the server [`hot.path`](#hotpath); set it to an absolute url (`wss://dev.example.com/__webpack_hmr`) for an endpoint on another origin or behind a proxy. |
607638
| `timeout` | `number` | `20000` | Heartbeat watchdog timeout in milliseconds, and the interval between reconnections under `"sse"`. |
608639
| `reconnect` | `number` | `10` | How many times `"ws"` reconnects before giving up. `"sse"` retries for as long as the page is open and ignores this. |
609640
| `overlay` | `boolean\|Object` | `true` | In-page overlay for problems: a boolean, or a JSON object — see [overlay options](#client-overlay-options). Same value shape as webpack-dev-server's [`client.overlay`](https://webpack.js.org/configuration/dev-server/#overlay), plus a few webpack-dev-middleware extensions. |
610-
| `hot` | `boolean` | `true` | Apply a build through Hot Module Replacement. Set to `false` for a project without `HotModuleReplacementPlugin`, and the page is reloaded instead — see `live-reload`. |
611-
| `live-reload` | `boolean` | `true` | Reload the page on a build that changed something, when `hot` is off. A build that changed nothing is left alone. Set both this and `hot` to `false` and a build reaches the page only when you reload it yourself. |
612-
| `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. Unrelated to `live-reload`: this one is about an update that was tried. |
613-
| `urlPrefix` | `string` | `"webpack-dev-middleware"` | Names the page-url parameters that turn `hot` and `live-reload` off for a single page — see [opting one page out](#opting-one-page-out). Change it if you are building a server of your own and want parameters named after it. |
641+
| `hot` | `boolean` | `true` | Apply a build through Hot Module Replacement. Set to `false` for a project without `HotModuleReplacementPlugin`, and the page is reloaded instead — see `liveReload`. |
642+
| `liveReload` | `boolean` | `true` | Reload the page on a build that changed something, when `hot` is off. A build that changed nothing is left alone. Set both this and `hot` to `false` and a build reaches the page only when you reload it yourself. |
643+
| `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. Unrelated to `liveReload`: this one is about an update that was tried. |
644+
| `urlPrefix` | `string` | `"webpack-dev-middleware"` | Names the page-url parameters that turn `hot` and `liveReload` off for a single page — see [opting one page out](#opting-one-page-out). Change it if you are building a server of your own and want parameters named after it. |
614645
| `logging` | `string` | `"info"` | Logger level — one of `"none"`, `"error"`, `"warn"`, `"info"`, `"log"`, `"verbose"`. Uses webpack's runtime logger. |
615646
| `name` | `string` | `""` | Restrict updates to a specific compilation name (useful with multi-compiler). |
616647
| `autoConnect` | `boolean` | `true` | Connect on load; set to `false` and call `setOptionsAndConnect()` manually. |
@@ -813,22 +844,22 @@ Three layers, from build to presentation:
813844

814845
### Opting one page out
815846

816-
A page can turn `hot` or `live-reload` off for itself with a url parameter,
847+
A page can turn `hot` or `liveReload` off for itself with a url parameter,
817848
without changing anything the project is configured with — useful when you are
818849
working _in_ a page that keeps reloading under you:
819850

820851
```
821-
http://localhost:3000/?webpack-dev-middleware-live-reload=false
852+
http://localhost:3000/?webpack-dev-middleware-liveReload=false
822853
http://localhost:3000/?webpack-dev-middleware-hot=false
823854
```
824855

825-
The `webpack-dev-middleware` part is the client's [`urlPrefix`](#client-options). The name is matched whole and case-insensitively, and only the value `false` turns anything off — a parameter that merely contains those words, or a value such as `falsehood`, is left alone.
856+
The `webpack-dev-middleware` part is the client's [`urlPrefix`](#client-options), so a server built on this middleware can set `hot.client.urlPrefix` and name these parameters after itself. What follows it is the option, spelled the one way the option is spelled. The name is matched whole and case-insensitively, and only the value `false` turns anything off — a parameter that merely contains those words, or a value such as `falsehood`, is left alone.
826857

827858
### Reloading the page from the server
828859

829860
Some changes belong to no compilation — a file served straight from disk, for
830861
instance — so nothing tells the page it is stale. Publish a `reload` and it
831-
loads itself again, whatever `hot` and `live-reload` are set to:
862+
loads itself again, whatever `hot` and `liveReload` are set to:
832863

833864
```js
834865
const instance = middleware(compiler, { hot: true });

‎client-src/index.js‎

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -134,10 +134,12 @@ setLogLevel(options.logging);
134134
/**
135135
* Whether one of the page's own url parameters turns a setting off, which is
136136
* how a single tab opts out of what the rest of the project is configured for
137-
* — `?webpack-dev-middleware-live-reload=false` to stop a page reloading under
137+
* — `?webpack-dev-middleware-liveReload=false` to stop a page reloading under
138138
* you while you work in it, for instance. `urlPrefix` names them, so a server
139-
* built on this middleware can keep the parameters its users already know.
140-
* @param {string} setting `hot` or `live-reload`
139+
* built on this middleware can name them after itself.
140+
*
141+
* The parameter is the option, spelled the one way the option is spelled.
142+
* @param {("hot" | "liveReload")} setting which option the page may have turned off
141143
* @returns {boolean} whether the page turned it off
142144
*/
143145
function turnedOffByUrl(setting) {
@@ -172,10 +174,8 @@ function setOverrides(overrides) {
172174
if (overrides.transport === "sse" || overrides.transport === "ws") {
173175
options.transport = overrides.transport;
174176
}
175-
// webpack-dev-server spells the endpoint `webSocketURL`, and unlike `path`
176-
// it carries the origin as well, which is what lets the page reach a server
177-
// on another host.
178-
if (overrides.webSocketURL) options.path = overrides.webSocketURL;
177+
// Where the page connects, which may be an absolute url rather than a path
178+
// when the endpoint is on another origin.
179179
if (overrides.path) options.path = overrides.path;
180180
if (overrides.timeout) {
181181
const timeout = Number(overrides.timeout);
@@ -216,12 +216,9 @@ function setOverrides(overrides) {
216216
}
217217
}
218218
if (overrides.hot) options.hot = overrides.hot !== "false";
219-
// Two different things, and webpack-dev-server spells them the same way:
220-
// `live-reload` is what happens on a build when `hot` is off, `reload` is
221-
// what happens when an update was tried and could not be applied.
222-
if (overrides["live-reload"]) {
223-
options.liveReload = overrides["live-reload"] !== "false";
224-
}
219+
// Two different things: `liveReload` is what happens on a build when `hot`
220+
// is off, `reload` is what happens when an update was tried and could not be
221+
// applied.
225222
if (overrides.liveReload) {
226223
options.liveReload = overrides.liveReload !== "false";
227224
}
@@ -608,7 +605,7 @@ function processMessage(obj) {
608605
// the page is already running.
609606
obj.action === "built" &&
610607
options.liveReload &&
611-
!turnedOffByUrl("live-reload")
608+
!turnedOffByUrl("liveReload")
612609
) {
613610
log.info("App updated. Reloading...");
614611
reloadPage();

0 commit comments

Comments
 (0)