fix(overlay): keep a runtime error raised during the initial load

.changeset/fix-overlay-dismissed-on-initial-load.md

@@ -0,0 +1,5 @@
+---
+"webpack-dev-server": patch
+---
+
+Keep the overlay for a runtime error thrown while the page is still loading.

client-src/index.js

@@ -451,6 +451,8 @@ const onSocketMessage = {
     log.info("App updated. Recompiling...");
 
     // Fixes #1042. overlay doesn't clear if errors are fixed but warnings remain.
+    // A rebuild replaces the code a runtime error came from too, so unlike
+    // `ok`/`still-ok` this clears that overlay as well.
     if (options.overlay) {
       overlay.send({ type: "DISMISS" });
     }
@@ -521,7 +523,7 @@ const onSocketMessage = {
     log.info("Nothing changed.");
 
     if (options.overlay) {
-      overlay.send({ type: "DISMISS" });
+      overlay.send({ type: "BUILD_OK" });
     }
 
     sendMessage("StillOk");
@@ -530,7 +532,7 @@ const onSocketMessage = {
     sendMessage("Ok");
 
     if (options.overlay) {
-      overlay.send({ type: "DISMISS" });
+      overlay.send({ type: "BUILD_OK" });
     }
 
     reloadApp(options, status);

client-src/overlay.js

@@ -145,6 +145,15 @@ const createOverlayMachine = (options) => {
               target: "hidden",
               actions: ["dismissMessages", "hideOverlay"],
             },
+            // WHY: A compilation reporting success says nothing about a runtime
+            // error, so it clears build errors only — no state but this one
+            // handles it, and an unhandled event is a no-op. Dismissing on the
+            // initial handshake's `ok` is what closed an overlay raised while
+            // the page was still loading (#5024).
+            BUILD_OK: {
+              target: "hidden",
+              actions: ["dismissMessages", "hideOverlay"],
+            },
             BUILD_ERROR: {
               target: "displayBuildError",
               actions: ["appendMessages", "showOverlay"],

test/client/index.test.js

@@ -98,13 +98,15 @@ describe("index", () => {
 
     t.assert.snapshot(log.log.info.mock.calls[1][0]);
     t.assert.snapshot(sendMessage.mock.calls[0][0]);
-    expect(overlay.send).not.toHaveBeenCalledWith({ type: "DISMISS" });
+    expect(overlay.send).not.toHaveBeenCalledWith({ type: "BUILD_OK" });
 
     // change flags
     onSocketMessage.overlay(true);
     onSocketMessage["still-ok"]();
 
-    expect(overlay.send).toHaveBeenCalledWith({ type: "DISMISS" });
+    // An unchanged compilation clears a build error only, never a runtime one.
+    expect(overlay.send).toHaveBeenCalledWith({ type: "BUILD_OK" });
+    expect(overlay.send).not.toHaveBeenCalledWith({ type: "DISMISS" });
   });
 
   it("should run onSocketMessage.progress and onSocketMessage['progress-update']", (t) => {
@@ -158,6 +160,21 @@ describe("index", () => {
     expect(res).toBeUndefined();
   });
 
+  it("should clear only build errors when a compilation succeeds", () => {
+    onSocketMessage.overlay(true);
+
+    // A rebuild replaces the code a runtime error came from, so it clears both.
+    onSocketMessage.invalid();
+
+    expect(overlay.send).toHaveBeenCalledWith({ type: "DISMISS" });
+
+    // A successful compilation says nothing about a runtime error — see #5024.
+    onSocketMessage.ok();
+
+    expect(overlay.send).toHaveBeenCalledWith({ type: "BUILD_OK" });
+    expect(overlay.send.mock.calls).toHaveLength(2);
+  });
+
   it("should run onSocketMessage['static-changed']", (t) => {
     onSocketMessage["static-changed"]();
 

test/client/overlay-lifecycle.test.js

@@ -11,6 +11,12 @@ const buildError = (messages) => ({
   messages,
 });
 
+const runtimeError = (messages) => ({
+  type: "RUNTIME_ERROR",
+  level: "error",
+  messages,
+});
+
 const loadOverlay = () => {
   const iframe = document.querySelector("#webpack-dev-server-client-overlay");
 
@@ -68,6 +74,29 @@ describe("overlay lifecycle", () => {
     expect(document.body.contains(iframe)).toBe(false);
   });
 
+  it("lets a successful compilation clear a build error but not a runtime one", () => {
+    const overlay = createOverlay({});
+
+    overlay.send(buildError(["build error"]));
+    const buildIframe = loadOverlay();
+
+    overlay.send({ type: "BUILD_OK" });
+    expect(document.body.contains(buildIframe)).toBe(false);
+
+    overlay.send(runtimeError(["runtime error"]));
+    const runtimeIframe = loadOverlay();
+
+    // The compilation succeeded, so it knows nothing about this error — see #5024.
+    overlay.send({ type: "BUILD_OK" });
+    expect(document.body.contains(runtimeIframe)).toBe(true);
+    expect(runtimeIframe.contentDocument.body.textContent).toContain(
+      "runtime error",
+    );
+
+    overlay.send({ type: "DISMISS" });
+    expect(document.body.contains(runtimeIframe)).toBe(false);
+  });
+
   it("reuses its Trusted Types policy and encodes editor paths", () => {
     const createPolicy = fn(() => ({ createHTML: (value) => value }));
     globalThis.trustedTypes = { createPolicy };

test/e2e/overlay.test.js

@@ -1709,6 +1709,51 @@ describe("overlay", () => {
     }
   });
 
+  it("should keep the overlay for a runtime error thrown during the initial load", async () => {
+    const compiler = webpack({
+      ...config,
+      entry: "./throw-on-initial-load.js",
+    });
+
+    const server = new Server(
+      {
+        port,
+      },
+      compiler,
+    );
+
+    await server.start();
+
+    const { page, browser } = await runBrowser();
+
+    try {
+      await page.goto(`http://localhost:${port}/`, {
+        waitUntil: "networkidle0",
+      });
+
+      // The entry throws while the page is still loading, so the overlay is up
+      // before the socket handshake reports the (successful) compilation. That
+      // `ok` used to dismiss it milliseconds later — see #5024.
+      await waitForExpect(async () => {
+        const overlayHandle = await page.$(
+          "#webpack-dev-server-client-overlay",
+        );
+
+        expect(overlayHandle).not.toBeNull();
+
+        const overlayFrame = await overlayHandle.contentFrame();
+        const overlayText = await overlayFrame.evaluate(
+          () => document.body.textContent,
+        );
+
+        expect(overlayText).toContain("Injected error");
+      });
+    } finally {
+      await browser.close();
+      await server.stop();
+    }
+  });
+
   it("should not show filtered runtime error", async () => {
     const compiler = webpack(config);
 

test/fixtures/overlay-config/throw-on-initial-load.js

@@ -0,0 +1,3 @@
+// Throws while the entry is still evaluating, i.e. before the client's socket
+// handshake completes. Compilation succeeds, so the handshake reports `ok`.
+throw new Error("Injected error");