feat(@angular/build): add --inspect option to the dev-server

This commit introduces an `--inspect` option to the dev-server, enabling debugging of server-side code when using SSR or SSG. This option is equivalent to `node --inspect=[[host:]port]`.

Usage examples:
```
$ ng serve --inspect
$ ng serve --inspect 9999
$ ng serve --inspect localhost:9999
```

Closes: #27773

goldens/public-api/angular/build/index.api.md

@@ -114,6 +114,7 @@ export interface DevServerBuilderOptions {
     };
     hmr?: boolean;
     host?: string;
+    inspect?: Inspect;
     liveReload?: boolean;
     open?: boolean;
     poll?: number;

goldens/public-api/angular_devkit/build_angular/index.api.md

@@ -126,6 +126,7 @@ export interface DevServerBuilderOptions {
     };
     hmr?: boolean;
     host?: string;
+    inspect?: Inspect;
     liveReload?: boolean;
     open?: boolean;
     poll?: number;

packages/angular/build/src/builders/dev-server/options.ts

@@ -63,6 +63,29 @@ export async function normalizeOptions(
     }
   }
 
+  let inspect: false | { host?: string; port?: number } = false;
+  const inspectRaw = options.inspect;
+  if (inspectRaw === true || inspectRaw === '' || inspectRaw === 'true') {
+    inspect = {
+      host: undefined,
+      port: undefined,
+    };
+  } else if (typeof inspectRaw === 'string' && inspectRaw !== 'false') {
+    const port = +inspectRaw;
+    if (isFinite(port)) {
+      inspect = {
+        host: undefined,
+        port,
+      };
+    } else {
+      const [host, port] = inspectRaw.split(':');
+      inspect = {
+        host,
+        port: isNaN(+port) ? undefined : +port,
+      };
+    }
+  }
+
   // Initial options to keep
   const {
     host,
@@ -104,5 +127,6 @@ export async function normalizeOptions(
     sslKey,
     // Prebundling defaults to true but requires caching to function
     prebundle: cacheOptions.enabled && !optimization.scripts && prebundle,
+    inspect,
   };
 }

packages/angular/build/src/builders/dev-server/schema.json

@@ -79,6 +79,17 @@
       "type": "number",
       "description": "Enable and define the file watching poll time period in milliseconds."
     },
+    "inspect": {
+      "default": false,
+      "description": "Activate debugging inspector. This option only has an effect when 'SSR' or 'SSG' are enabled.",
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Activate the inspector on host and port in the format of `[[host:]port]`. See the security warning in https://nodejs.org/docs/latest-v22.x/api/cli.html#warning-binding-inspector-to-a-public-ipport-combination-is-insecure regarding the host parameter usage."
+        },
+        { "type": "boolean" }
+      ]
+    },
     "prebundle": {
       "description": "Enable and control the Vite-based development server's prebundling capabilities. To enable prebundling, the Angular CLI cache must also be enabled.",
       "default": true,

packages/angular/build/src/builders/dev-server/vite-server.ts

@@ -10,6 +10,7 @@ import type { BuilderContext } from '@angular-devkit/architect';
 import type { Plugin } from 'esbuild';
 import assert from 'node:assert';
 import { readFile } from 'node:fs/promises';
+import inspector from 'node:inspector';
 import { builtinModules } from 'node:module';
 import { basename, join } from 'node:path';
 import type { Connect, DepOptimizationConfig, InlineConfig, ViteDevServer } from 'vite';
@@ -262,6 +263,12 @@ export async function* serveWithVite(
         'NOTE: Raw file sizes do not reflect development server per-request transformations.',
       );
 
+      if (browserOptions.ssr && serverOptions.inspect) {
+        const { host, port } = serverOptions.inspect as { host?: string; port?: number };
+        inspector.open(port, host, true);
+        context.addTeardown(() => inspector.close());
+      }
+
       const { root = '' } = await context.getProjectMetadata(projectName);
       const projectRoot = join(context.workspaceRoot, root as string);
       const browsers = getSupportedBrowsers(projectRoot, context.logger);

packages/angular_devkit/build_angular/src/builders/dev-server/options.ts

@@ -61,6 +61,29 @@ export async function normalizeOptions(
     }
   }
 
+  let inspect: false | { host?: string; port?: number } = false;
+  const inspectRaw = options.inspect;
+  if (inspectRaw === true || inspectRaw === '' || inspectRaw === 'true') {
+    inspect = {
+      host: undefined,
+      port: undefined,
+    };
+  } else if (typeof inspectRaw === 'string' && inspectRaw !== 'false') {
+    const port = +inspectRaw;
+    if (isFinite(port)) {
+      inspect = {
+        host: undefined,
+        port,
+      };
+    } else {
+      const [host, port] = inspectRaw.split(':');
+      inspect = {
+        host,
+        port: isNaN(+port) ? undefined : +port,
+      };
+    }
+  }
+
   // Initial options to keep
   const {
     host,
@@ -110,5 +133,6 @@ export async function normalizeOptions(
     forceEsbuild,
     // Prebundling defaults to true but requires caching to function
     prebundle: cacheOptions.enabled && !optimization.scripts && (prebundle ?? true),
+    inspect,
   };
 }

packages/angular_devkit/build_angular/src/builders/dev-server/schema.json

@@ -102,6 +102,17 @@
       "type": "number",
       "description": "Enable and define the file watching poll time period in milliseconds."
     },
+    "inspect": {
+      "default": false,
+      "description": "Activate debugging inspector. This option only has an effect when 'SSR' or 'SSG' are enabled.",
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Activate the inspector on host and port in the format of `[[host:]port]`. See the security warning in https://nodejs.org/docs/latest-v22.x/api/cli.html#warning-binding-inspector-to-a-public-ipport-combination-is-insecure regarding the host parameter usage."
+        },
+        { "type": "boolean" }
+      ]
+    },
     "forceEsbuild": {
       "type": "boolean",
       "description": "Force the development server to use the 'browser-esbuild' builder when building. This is a developer preview option for the esbuild-based build system.",