fix(@angular/build): add define option to dev-server

This change introduces a `define` option to the dev-server builder, allowing users to specify global constants that will be replaced at build time. This provides a convenient way to configure environment-specific variables directly from the dev-server configuration.

(cherry picked from commit 4211534)

Author: clydin

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

@@ -112,6 +112,9 @@ export enum BuildOutputFileType {
 export type DevServerBuilderOptions = {
     allowedHosts?: AllowedHosts;
     buildTarget: string;
+    define?: {
+        [key: string]: string;
+    };
     headers?: {
         [key: string]: string;
     };

modules/testing/builder/src/builder-harness.ts

@@ -162,6 +162,24 @@ export class BuilderHarness<T> {
     return this;
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  modifyTarget<O extends object = any>(
+    targetName: string,
+    modifier: (options: O) => O | void,
+  ): this {
+    const target = this.builderTargets.get(targetName);
+    if (!target) {
+      throw new Error(`Target "${targetName}" not found.`);
+    }
+
+    const newOptions = modifier(target.options as O);
+    if (newOptions) {
+      target.options = newOptions as json.JsonObject;
+    }
+
+    return this;
+  }
+
   execute(
     options: Partial<BuilderHarnessExecutionOptions> = {},
   ): Observable<BuilderHarnessExecutionResult> {

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

@@ -93,6 +93,7 @@ export async function normalizeOptions(
     poll,
     open,
     verbose,
+    define,
     watch,
     liveReload,
     hmr,
@@ -114,6 +115,7 @@ export async function normalizeOptions(
     poll,
     open,
     verbose,
+    define,
     watch,
     liveReload: !!liveReload,
     hmr: hmr ?? !!liveReload,

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

@@ -53,6 +53,13 @@
         }
       ]
     },
+    "define": {
+      "description": "Defines global identifiers that will be replaced with a specified constant value when found in any JavaScript or TypeScript code including libraries. The value will be used directly. String values must be put in quotes. Identifiers within Angular metadata such as Component Decorators will not be replaced.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
     "headers": {
       "type": "object",
       "description": "Custom HTTP headers to be added to all responses.",

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

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { executeDevServer } from '../../index';
+import { executeOnceAndFetch } from '../execute-fetch';
+import { describeServeBuilder } from '../jasmine-helpers';
+import { BASE_OPTIONS, DEV_SERVER_BUILDER_INFO } from '../setup';
+
+describeServeBuilder(executeDevServer, DEV_SERVER_BUILDER_INFO, (harness, setupTarget) => {
+  describe('option: "define"', () => {
+    beforeEach(() => {
+      setupTarget(harness);
+
+      // Application code
+      harness.writeFile(
+        'src/main.ts',
+        `
+        // @ts-ignore
+        console.log(TEST);
+        // @ts-ignore
+        console.log(BUILD);
+        // @ts-ignore
+        console.log(SERVE);
+      `,
+      );
+    });
+
+    it('should replace global identifiers in the application', async () => {
+      harness.useTarget('serve', {
+        ...BASE_OPTIONS,
+        define: {
+          TEST: JSON.stringify('test123'),
+        },
+      });
+
+      const { result, response } = await executeOnceAndFetch(harness, '/main.js');
+
+      expect(result?.success).toBeTrue();
+      const content = await response?.text();
+      expect(content).toContain('console.log("test123")');
+    });
+
+    it('should merge "define" option from dev-server and build', async () => {
+      harness.modifyTarget('build', (options) => {
+        options.define = {
+          BUILD: JSON.stringify('build'),
+        };
+      });
+
+      harness.useTarget('serve', {
+        ...BASE_OPTIONS,
+        define: {
+          SERVE: JSON.stringify('serve'),
+        },
+      });
+
+      const { result, response } = await executeOnceAndFetch(harness, '/main.js');
+
+      expect(result?.success).toBeTrue();
+      const content = await response?.text();
+      expect(content).toContain('console.log("build")');
+      expect(content).toContain('console.log("serve")');
+    });
+
+    it('should overwrite "define" option from build with the one from dev-server', async () => {
+      harness.modifyTarget('build', (options) => {
+        options.define = {
+          TEST: JSON.stringify('build'),
+        };
+      });
+
+      harness.useTarget('serve', {
+        ...BASE_OPTIONS,
+        define: {
+          TEST: JSON.stringify('serve'),
+        },
+      });
+
+      const { result, response } = await executeOnceAndFetch(harness, '/main.js');
+
+      expect(result?.success).toBeTrue();
+      const content = await response?.text();
+      expect(content).toContain('console.log("serve")');
+      expect(content).not.toContain('console.log("build")');
+    });
+  });
+});

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

@@ -49,7 +49,7 @@ export type BuilderAction = (
  * Build options that are also present on the dev server but are only passed
  * to the build.
  */
-const CONVENIENCE_BUILD_OPTIONS = ['watch', 'poll', 'verbose'] as const;
+const CONVENIENCE_BUILD_OPTIONS = ['watch', 'poll', 'verbose', 'define'] as const;
 
 // eslint-disable-next-line max-lines-per-function
 export async function* serveWithVite(
@@ -75,7 +75,15 @@ export async function* serveWithVite(
   for (const optionName of CONVENIENCE_BUILD_OPTIONS) {
     const optionValue = serverOptions[optionName];
     if (optionValue !== undefined) {
-      rawBrowserOptions[optionName] = optionValue;
+      if (optionName === 'define' && rawBrowserOptions[optionName]) {
+        // Define has merging behavior within the application
+        for (const [key, value] of Object.entries(optionValue)) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (rawBrowserOptions[optionName] as any)[key] = value;
+        }
+      } else {
+        rawBrowserOptions[optionName] = optionValue;
+      }
     }
   }
 

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

@@ -97,6 +97,7 @@ export function execute(
               normalizedOptions as typeof normalizedOptions & {
                 hmr: boolean;
                 allowedHosts: true | string[];
+                define: { [key: string]: string } | undefined;
               },
               builderName,
               (options, context, codePlugins) => {