fix(@angular/build): handle external @angular/ packages during SSR

This commit introduces `ngServerMode` to ensure proper handling of external `@angular/` packages when they are used as externals during server-side rendering (SSR).

Closes: #29092

Author: alan-agius4

packages/angular/build/src/tools/esbuild/application-code-bundle.ts

@@ -200,6 +200,16 @@ export function createServerPolyfillBundleOptions(
     return;
   }
 
+  const jsBanner: string[] = [`globalThis['ngServerMode'] = true;`];
+  if (isNodePlatform) {
+    // Note: Needed as esbuild does not provide require shims / proxy from ESModules.
+    // See: https://github.com/evanw/esbuild/issues/1921.
+    jsBanner.push(
+      `import { createRequire } from 'node:module';`,
+      `globalThis['require'] ??= createRequire(import.meta.url);`,
+    );
+  }
+
   const buildOptions: BuildOptions = {
     ...polyfillBundleOptions,
     platform: isNodePlatform ? 'node' : 'neutral',
@@ -210,16 +220,9 @@ export function createServerPolyfillBundleOptions(
     // More details: https://github.com/angular/angular-cli/issues/25405.
     mainFields: ['es2020', 'es2015', 'module', 'main'],
     entryNames: '[name]',
-    banner: isNodePlatform
-      ? {
-          js: [
-            // Note: Needed as esbuild does not provide require shims / proxy from ESModules.
-            // See: https://github.com/evanw/esbuild/issues/1921.
-            `import { createRequire } from 'node:module';`,
-            `globalThis['require'] ??= createRequire(import.meta.url);`,
-          ].join('\n'),
-        }
-      : undefined,
+    banner: {
+      js: jsBanner.join('\n'),
+    },
     target,
     entryPoints: {
       'polyfills.server': namespace,
@@ -391,19 +394,22 @@ export function createSsrEntryCodeBundleOptions(
     const ssrInjectManifestNamespace = 'angular:ssr-entry-inject-manifest';
     const isNodePlatform = options.ssrOptions?.platform !== ExperimentalPlatform.Neutral;
 
+    const jsBanner: string[] = [`globalThis['ngServerMode'] = true;`];
+    if (isNodePlatform) {
+      // Note: Needed as esbuild does not provide require shims / proxy from ESModules.
+      // See: https://github.com/evanw/esbuild/issues/1921.
+      jsBanner.push(
+        `import { createRequire } from 'node:module';`,
+        `globalThis['require'] ??= createRequire(import.meta.url);`,
+      );
+    }
+
     const buildOptions: BuildOptions = {
       ...getEsBuildServerCommonOptions(options),
       target,
-      banner: isNodePlatform
-        ? {
-            js: [
-              // Note: Needed as esbuild does not provide require shims / proxy from ESModules.
-              // See: https://github.com/evanw/esbuild/issues/1921.
-              `import { createRequire } from 'node:module';`,
-              `globalThis['require'] ??= createRequire(import.meta.url);`,
-            ].join('\n'),
-          }
-        : undefined,
+      banner: {
+        js: jsBanner.join('\n'),
+      },
       entryPoints: {
         'server': ssrEntryNamespace,
       },

packages/angular/build/src/utils/server-rendering/esm-in-memory-loader/loader-hooks.ts

@@ -133,7 +133,11 @@ export async function load(url: string, context: { format?: string | null }, nex
   // need linking are ESM only.
   if (format === 'module' && isFileProtocol(url)) {
     const filePath = fileURLToPath(url);
-    const source = await javascriptTransformer.transformFile(filePath);
+    let source = await javascriptTransformer.transformFile(filePath);
+
+    if (filePath.includes('@angular/')) {
+      source = prependNgServerMode(source);
+    }
 
     return {
       format,
@@ -154,6 +158,26 @@ function handleProcessExit(): void {
   void javascriptTransformer.close();
 }
 
+/**
+ * @note For some unknown reason, setting `globalThis.ngServerMode = true` does not work when using ESM loader hooks.
+ */
+const NG_SERVER_MODE_INIT_BYTES = new TextEncoder().encode('var ngServerMode=true;');
+
+/**
+ * Prepend the hardcoded string 'var ngServerMode=true;' to a Uint8Array.
+ *
+ * @param inputArray - The original Uint8Array to which the hardcoded string will be prepended.
+ * @returns A new Uint8Array containing the hardcoded string followed by the input Uint8Array content.
+ */
+function prependNgServerMode(inputArray: Uint8Array): Uint8Array {
+  const combinedLength = NG_SERVER_MODE_INIT_BYTES.length + inputArray.length;
+  const combinedArray = new Uint8Array(combinedLength);
+  combinedArray.set(NG_SERVER_MODE_INIT_BYTES, 0);
+  combinedArray.set(inputArray, NG_SERVER_MODE_INIT_BYTES.length);
+
+  return combinedArray;
+}
+
 process.once('exit', handleProcessExit);
 process.once('SIGINT', handleProcessExit);
 process.once('uncaughtException', handleProcessExit);

tests/legacy-cli/e2e/tests/build/server-rendering/server-routes-output-mode-server-external-dependencies.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert';
+import { ng } from '../../../utils/process';
+import { installWorkspacePackages, uninstallPackage } from '../../../utils/packages';
+import { updateJsonFile, useSha } from '../../../utils/project';
+import { getGlobalVariable } from '../../../utils/env';
+
+export default async function () {
+  assert(
+    getGlobalVariable('argv')['esbuild'],
+    'This test should not be called in the Webpack suite.',
+  );
+
+  // Forcibly remove in case another test doesn't clean itself up.
+  await uninstallPackage('@angular/ssr');
+  await ng('add', '@angular/ssr', '--server-routing', '--skip-confirmation', '--skip-install');
+  await useSha();
+  await installWorkspacePackages();
+
+  await updateJsonFile('angular.json', (json) => {
+    const build = json['projects']['test-project']['architect']['build'];
+    build.options.externalDependencies = [
+      '@angular/platform-browser',
+      '@angular/core',
+      '@angular/router',
+      '@angular/common',
+      '@angular/common/http',
+      '@angular/platform-browser/animations',
+    ];
+  });
+
+  await ng('build');
+}