feat(@angular/build): introduce ssr.experimentalPlatform option

This commit introduces a new option called `experimentalPlatform` to the Angular SSR configuration.

The `experimentalPlatform` option allows developers to specify the target platform for the server bundle, enabling the generation of platform-neutral bundles suitable for deployment in environments like edge workers and other serverless platforms that do not rely on Node.js APIs.

This change enhances the portability of Angular SSR applications and expands their deployment possibilities.

**Note:** that this feature does not include polyfills for Node.js modules and is experimental, subject to future changes.

Author: alan-agius4

packages/angular/build/src/builders/application/options.ts

@@ -27,6 +27,7 @@ import {
 import { urlJoin } from '../../utils/url';
 import {
   Schema as ApplicationBuilderOptions,
+  ExperimentalPlatform,
   I18NTranslation,
   OutputHashing,
   OutputMode,
@@ -264,10 +265,11 @@ export async function normalizeOptions(
   if (options.ssr === true) {
     ssrOptions = {};
   } else if (typeof options.ssr === 'object') {
-    const { entry } = options.ssr;
+    const { entry, experimentalPlatform = ExperimentalPlatform.Node } = options.ssr;
 
     ssrOptions = {
       entry: entry && path.join(workspaceRoot, entry),
+      platform: experimentalPlatform,
     };
   }
 

packages/angular/build/src/builders/application/schema.json

@@ -518,6 +518,11 @@
             "entry": {
               "type": "string",
               "description": "The server entry-point that when executed will spawn the web server."
+            },
+            "experimentalPlatform": {
+              "description": "Specifies the platform for which the server bundle is generated. This affects the APIs and modules available in the server-side code. \n\n- `node`:  (Default) Generates a bundle optimized for Node.js environments. \n- `neutral`: Generates a platform-neutral bundle suitable for environments like edge workers, and other serverless platforms. This option avoids using Node.js-specific APIs, making the bundle more portable. \n\nPlease note that this feature does not provide polyfills for Node.js modules. Additionally, it is experimental, and the schematics may undergo changes in future versions.",
+              "default": "node",
+              "enum": ["node", "neutral"]
             }
           },
           "additionalProperties": false

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

@@ -11,6 +11,7 @@ import assert from 'node:assert';
 import { createHash } from 'node:crypto';
 import { extname, relative } from 'node:path';
 import type { NormalizedApplicationBuildOptions } from '../../builders/application/options';
+import { ExperimentalPlatform } from '../../builders/application/schema';
 import { allowMangle } from '../../utils/environment-options';
 import {
   SERVER_APP_ENGINE_MANIFEST_FILENAME,
@@ -160,8 +161,10 @@ export function createServerPolyfillBundleOptions(
 ): BundlerOptionsFactory | undefined {
   const serverPolyfills: string[] = [];
   const polyfillsFromConfig = new Set(options.polyfills);
+  const isNodePlatform = options.ssrOptions?.platform !== ExperimentalPlatform.Neutral;
+
   if (!isZonelessApp(options.polyfills)) {
-    serverPolyfills.push('zone.js/node');
+    serverPolyfills.push(isNodePlatform ? 'zone.js/node' : 'zone.js');
   }
 
   if (
@@ -190,22 +193,24 @@ export function createServerPolyfillBundleOptions(
 
   const buildOptions: BuildOptions = {
     ...polyfillBundleOptions,
-    platform: 'node',
+    platform: isNodePlatform ? 'node' : 'neutral',
     outExtension: { '.js': '.mjs' },
     // Note: `es2015` is needed for RxJS v6. If not specified, `module` would
     // match and the ES5 distribution would be bundled and ends up breaking at
     // runtime with the RxJS testing library.
     // More details: https://github.com/angular/angular-cli/issues/25405.
     mainFields: ['es2020', 'es2015', 'module', 'main'],
     entryNames: '[name]',
-    banner: {
-      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'),
-    },
+    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,
     target,
     entryPoints: {
       'polyfills.server': namespace,
@@ -285,6 +290,14 @@ export function createServerMainCodeBundleOptions(
 
   // Mark manifest and polyfills file as external as these are generated by a different bundle step.
   (buildOptions.external ??= []).push(...SERVER_GENERATED_EXTERNALS);
+  const isNodePlatform = options.ssrOptions?.platform !== ExperimentalPlatform.Neutral;
+
+  if (!isNodePlatform) {
+    // `@angular/platform-server` lazily depends on `xhr2` for XHR usage with the HTTP client.
+    // Since `xhr2` has Node.js dependencies, it cannot be used when targeting non-Node.js platforms.
+    // Note: The framework already issues a warning when using XHR with SSR.
+    buildOptions.external.push('xhr2');
+  }
 
   buildOptions.plugins.push(
     createVirtualModulePlugin({
@@ -373,6 +386,13 @@ export function createSsrEntryCodeBundleOptions(
   const ssrEntryNamespace = 'angular:ssr-entry';
   const ssrInjectManifestNamespace = 'angular:ssr-entry-inject-manifest';
   const ssrInjectRequireNamespace = 'angular:ssr-entry-inject-require';
+  const isNodePlatform = options.ssrOptions?.platform !== ExperimentalPlatform.Neutral;
+
+  const inject: string[] = [ssrInjectManifestNamespace];
+  if (isNodePlatform) {
+    inject.unshift(ssrInjectRequireNamespace);
+  }
+
   const buildOptions: BuildOptions = {
     ...getEsBuildServerCommonOptions(options),
     target,
@@ -390,7 +410,7 @@ export function createSsrEntryCodeBundleOptions(
         styleOptions,
       ),
     ],
-    inject: [ssrInjectRequireNamespace, ssrInjectManifestNamespace],
+    inject,
   };
 
   buildOptions.plugins ??= [];
@@ -404,6 +424,13 @@ export function createSsrEntryCodeBundleOptions(
   // Mark manifest file as external. As this will be generated later on.
   (buildOptions.external ??= []).push('*/main.server.mjs', ...SERVER_GENERATED_EXTERNALS);
 
+  if (!isNodePlatform) {
+    // `@angular/platform-server` lazily depends on `xhr2` for XHR usage with the HTTP client.
+    // Since `xhr2` has Node.js dependencies, it cannot be used when targeting non-Node.js platforms.
+    // Note: The framework already issues a warning when using XHR with SSR.
+    buildOptions.external.push('xhr2');
+  }
+
   buildOptions.plugins.push(
     {
       name: 'angular-ssr-metadata',
@@ -490,9 +517,11 @@ export function createSsrEntryCodeBundleOptions(
 }
 
 function getEsBuildServerCommonOptions(options: NormalizedApplicationBuildOptions): BuildOptions {
+  const isNodePlatform = options.ssrOptions?.platform !== ExperimentalPlatform.Neutral;
+
   return {
     ...getEsBuildCommonOptions(options),
-    platform: 'node',
+    platform: isNodePlatform ? 'node' : 'neutral',
     outExtension: { '.js': '.mjs' },
     // Note: `es2015` is needed for RxJS v6. If not specified, `module` would
     // match and the ES5 distribution would be bundled and ends up breaking at

packages/angular/build/src/tools/esbuild/bundler-context.ts

@@ -423,7 +423,9 @@ export class BundlerContext {
   }
 
   get #platformIsServer(): boolean {
-    return this.#esbuildOptions?.platform === 'node';
+    return (
+      this.#esbuildOptions?.platform === 'node' || this.#esbuildOptions?.platform === 'neutral'
+    );
   }
 
   /**