Skip to content

feat(client): bring the error overlay to parity with webpack-dev-server #2353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bjohansebas merged 6 commits into from
Jul 20, 2026
Merged

feat(client): bring the error overlay to parity with webpack-dev-server #2353

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b31375a
feat(client): bring the error overlay to parity with webpack-dev-server
bjohansebas Jul 14, 2026
3da7b7b
feat(client): support opening file references in the editor
bjohansebas Jul 20, 2026
7ebe8fa
feat(client): bring the error overlay to parity with webpack-dev-server
bjohansebas Jul 20, 2026
a4c2f4f
fix(client): track overlay problems per compilation
bjohansebas Jul 20, 2026
f4aadf8
docs(examples): add a MultiCompiler hot example
bjohansebas Jul 20, 2026
47e037b
refactor(client): nest overlay extensions inside the overlay option
bjohansebas Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
"finalhandler",
"hono",
"rspack",
"apos",
"malformed"
],
"ignorePaths": [
Expand Down
41 changes: 28 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -375,19 +375,16 @@ entry: [

### 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` | `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. |
| `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. |
| 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\|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>`; the endpoint is provided by your server, e.g. a route calling [launch-editor](https://github.com/yyx990803/launch-editor)). |
| `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. |
| `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

Expand Down Expand Up @@ -426,6 +423,24 @@ hotClient.setOptionsAndConnect({ path: "/__hmr" });
hotClient.disconnect();
```

The error overlay is also exposed as a standalone module so other tooling
(e.g. `webpack-dev-server`) can reuse it without the SSE client:

```js
import configureOverlay, {
clear,
showProblems,
} from "webpack-dev-middleware/client/overlay";

const overlay = configureOverlay({
// ansiColors, overlayStyles, trustedTypesPolicyName, catchRuntimeError,
// openEditorEndpoint
});

overlay.showProblems("errors", ["Something broke"]);
overlay.clear();
```

## API

`webpack-dev-middleware` also provides convenience methods that can be use to
Expand Down
12 changes: 11 additions & 1 deletion client-src/globals.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ interface ClientReporter {
type: "errors" | "warnings",
obj: { errors: string[]; warnings: string[]; name?: string },
): boolean;
success(): void;
success(obj?: { name?: string }): void;
useCustomOverlay(customOverlay: unknown): void;
}

Expand All @@ -23,7 +23,17 @@ interface EventSourceWrapper {
close(): void;
}

interface OverlayTrustedTypesPolicy {
createHTML(value: string): string;
}

interface Window {
__wdmEventSourceWrapper?: Record<string, EventSourceWrapper>;
__webpack_dev_middleware_hot_reporter__?: ClientReporter;
trustedTypes?: {
createPolicy(
name: string,
rules: { createHTML(value: string): string },
): OverlayTrustedTypesPolicy;
};
}
Loading