feat: added client.overlay.runtimeErrors option to control runtime errors (#4773)

Author: malcolm-kee

bin/cli-flags.js

@@ -153,6 +153,23 @@ module.exports = {
     simpleType: "boolean",
     multiple: false,
   },
+  "client-overlay-runtime-errors": {
+    configs: [
+      {
+        type: "boolean",
+        multiple: false,
+        description:
+          "Enables a full-screen overlay in the browser when there are uncaught runtime errors.",
+        negatedDescription:
+          "Disables the full-screen overlay in the browser when there are uncaught runtime errors.",
+        path: "client.overlay.runtimeErrors",
+      },
+    ],
+    description:
+      "Enables a full-screen overlay in the browser when there are uncaught runtime errors.",
+    simpleType: "boolean",
+    multiple: false,
+  },
   "client-progress": {
     configs: [
       {

client-src/index.js

@@ -15,7 +15,7 @@ import createSocketURL from "./utils/createSocketURL.js";
  * @property {boolean} hot
  * @property {boolean} liveReload
  * @property {boolean} progress
- * @property {boolean | { warnings?: boolean, errors?: boolean, trustedTypesPolicyName?: string }} overlay
+ * @property {boolean | { warnings?: boolean, errors?: boolean, runtimeErrors?: boolean, trustedTypesPolicyName?: string }} overlay
  * @property {string} [logging]
  * @property {number} [reconnect]
  */
@@ -80,6 +80,7 @@ if (parsedResourceQuery.overlay) {
     options.overlay = {
       errors: true,
       warnings: true,
+      runtimeErrors: true,
       ...options.overlay,
     };
   }
@@ -115,12 +116,20 @@ self.addEventListener("beforeunload", () => {
   status.isUnloading = true;
 });
 
-const trustedTypesPolicyName =
-  typeof options.overlay === "object" && options.overlay.trustedTypesPolicyName;
-
-const overlay = createOverlay({
-  trustedTypesPolicyName,
-});
+const overlay =
+  typeof window !== "undefined"
+    ? createOverlay(
+        typeof options.overlay === "object"
+          ? {
+              trustedTypesPolicyName: options.overlay.trustedTypesPolicyName,
+              catchRuntimeError: options.overlay.runtimeErrors,
+            }
+          : {
+              trustedTypesPolicyName: false,
+              catchRuntimeError: options.overlay,
+            }
+      )
+    : { send: () => {} };
 
 const onSocketMessage = {
   hot() {

client-src/overlay.js

@@ -78,6 +78,7 @@ function formatProblem(type, item) {
 /**
  * @typedef {Object} CreateOverlayOptions
  * @property {string | null} trustedTypesPolicyName
+ * @property {boolean} [catchRuntimeError]
  */
 
 /**
@@ -271,24 +272,29 @@ const createOverlay = (options) => {
     hideOverlay: hide,
   });
 
-  listenToRuntimeError((errorEvent) => {
-    // error property may be empty in older browser like IE
-    const { error, message } = errorEvent;
-    if (!error && !message) {
-      return;
-    }
-    const errorObject =
-      error instanceof Error ? error : new Error(error || message);
-    overlayService.send({
-      type: "RUNTIME_ERROR",
-      messages: [
-        {
-          message: errorObject.message,
-          stack: parseErrorToStacks(errorObject),
-        },
-      ],
+  if (options.catchRuntimeError) {
+    listenToRuntimeError((errorEvent) => {
+      // error property may be empty in older browser like IE
+      const { error, message } = errorEvent;
+
+      if (!error && !message) {
+        return;
+      }
+
+      const errorObject =
+        error instanceof Error ? error : new Error(error || message);
+
+      overlayService.send({
+        type: "RUNTIME_ERROR",
+        messages: [
+          {
+            message: errorObject.message,
+            stack: parseErrorToStacks(errorObject),
+          },
+        ],
+      });
     });
-  });
+  }
 
   return overlayService;
 };

lib/Server.js

@@ -159,7 +159,7 @@ const schema = require("./options.json");
 /**
  * @typedef {Object} ClientConfiguration
  * @property {"log" | "info" | "warn" | "error" | "none" | "verbose"} [logging]
- * @property {boolean  | { warnings?: boolean, errors?: boolean }} [overlay]
+ * @property {boolean  | { warnings?: boolean, errors?: boolean, runtimeErrors?: boolean }} [overlay]
  * @property {boolean} [progress]
  * @property {boolean | number} [reconnect]
  * @property {"ws" | "sockjs" | string} [webSocketTransport]

lib/options.json

@@ -111,6 +111,13 @@
                 "negatedDescription": "Disables the full-screen overlay in the browser when there are compiler warnings."
               }
             },
+            "runtimeErrors": {
+              "description": "Enables a full-screen overlay in the browser when there are uncaught runtime errors.",
+              "type": "boolean",
+              "cli": {
+                "negatedDescription": "Disables the full-screen overlay in the browser when there are uncaught runtime errors."
+              }
+            },
             "trustedTypesPolicyName": {
               "description": "The name of a Trusted Types policy for the overlay. Defaults to 'webpack-dev-server#overlay'.",
               "type": "string"

test/__snapshots__/validate-options.test.js.snap.webpack4

@@ -90,19 +90,19 @@ exports[`options validate should throw an error on the "client" option with '{"o
    -> Read more at https://webpack.js.org/configuration/dev-server/#devserverclient
    Details:
     * options.client.overlay should be one of these:
-      boolean | object { errors?, warnings?, trustedTypesPolicyName? }
+      boolean | object { errors?, warnings?, runtimeErrors?, trustedTypesPolicyName? }
       Details:
        * options.client.overlay should be a boolean.
          -> Enables a full-screen overlay in the browser when there are compiler errors or warnings.
          -> Read more at https://webpack.js.org/configuration/dev-server/#overlay
        * options.client.overlay should be an object:
-         object { errors?, warnings?, trustedTypesPolicyName? }"
+         object { errors?, warnings?, runtimeErrors?, trustedTypesPolicyName? }"
 `;
 
 exports[`options validate should throw an error on the "client" option with '{"overlay":{"arbitrary":""}}' value 1`] = `
 "ValidationError: Invalid options object. Dev Server has been initialized using an options object that does not match the API schema.
  - options.client.overlay has an unknown property 'arbitrary'. These properties are valid:
-   object { errors?, warnings?, trustedTypesPolicyName? }"
+   object { errors?, warnings?, runtimeErrors?, trustedTypesPolicyName? }"
 `;
 
 exports[`options validate should throw an error on the "client" option with '{"overlay":{"errors":""}}' value 1`] = `

test/__snapshots__/validate-options.test.js.snap.webpack5

@@ -90,19 +90,19 @@ exports[`options validate should throw an error on the "client" option with '{"o
    -> Read more at https://webpack.js.org/configuration/dev-server/#devserverclient
    Details:
     * options.client.overlay should be one of these:
-      boolean | object { errors?, warnings?, trustedTypesPolicyName? }
+      boolean | object { errors?, warnings?, runtimeErrors?, trustedTypesPolicyName? }
       Details:
        * options.client.overlay should be a boolean.
          -> Enables a full-screen overlay in the browser when there are compiler errors or warnings.
          -> Read more at https://webpack.js.org/configuration/dev-server/#overlay
        * options.client.overlay should be an object:
-         object { errors?, warnings?, trustedTypesPolicyName? }"
+         object { errors?, warnings?, runtimeErrors?, trustedTypesPolicyName? }"
 `;
 
 exports[`options validate should throw an error on the "client" option with '{"overlay":{"arbitrary":""}}' value 1`] = `
 "ValidationError: Invalid options object. Dev Server has been initialized using an options object that does not match the API schema.
  - options.client.overlay has an unknown property 'arbitrary'. These properties are valid:
-   object { errors?, warnings?, trustedTypesPolicyName? }"
+   object { errors?, warnings?, runtimeErrors?, trustedTypesPolicyName? }"
 `;
 
 exports[`options validate should throw an error on the "client" option with '{"overlay":{"errors":""}}' value 1`] = `

test/cli/__snapshots__/basic.test.js.snap.webpack4

@@ -67,6 +67,8 @@ Options:
   --client-overlay-trusted-types-policy-name <value>  The name of a Trusted Types policy for the overlay. Defaults to 'webpack-dev-server#overlay'.
   --client-overlay-warnings                           Enables a full-screen overlay in the browser when there are compiler warnings.
   --no-client-overlay-warnings                        Disables the full-screen overlay in the browser when there are compiler warnings.
+  --client-overlay-runtime-errors                     Enables a full-screen overlay in the browser when there are uncaught runtime errors.
+  --no-client-overlay-runtime-errors                  Disables the full-screen overlay in the browser when there are uncaught runtime errors.
   --client-progress                                   Prints compilation progress in percentage in the browser.
   --no-client-progress                                Does not print compilation progress in percentage in the browser.
   --client-reconnect [value]                          Tells dev-server the number of times it should try to reconnect the client.

test/cli/__snapshots__/basic.test.js.snap.webpack5

@@ -67,6 +67,8 @@ Options:
   --no-client-overlay-errors                          Disables the full-screen overlay in the browser when there are compiler errors.
   --client-overlay-warnings                           Enables a full-screen overlay in the browser when there are compiler warnings.
   --no-client-overlay-warnings                        Disables the full-screen overlay in the browser when there are compiler warnings.
+  --client-overlay-runtime-errors                     Enables a full-screen overlay in the browser when there are uncaught runtime errors.
+  --no-client-overlay-runtime-errors                  Disables the full-screen overlay in the browser when there are uncaught runtime errors.
   --client-overlay-trusted-types-policy-name <value>  The name of a Trusted Types policy for the overlay. Defaults to 'webpack-dev-server#overlay'.
   --client-progress                                   Prints compilation progress in percentage in the browser.
   --no-client-progress                                Does not print compilation progress in percentage in the browser.

types/bin/cli-flags.d.ts

@@ -114,6 +114,18 @@ declare const _exports: {
     simpleType: string;
     multiple: boolean;
   };
+  "client-overlay-runtime-errors": {
+    configs: {
+      type: string;
+      multiple: boolean;
+      description: string;
+      negatedDescription: string;
+      path: string;
+    }[];
+    description: string;
+    simpleType: string;
+    multiple: boolean;
+  };
   "client-progress": {
     configs: {
       type: string;