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

@@ -28,6 +28,7 @@ import { createSourcemapIgnorelistPlugin } from './sourcemap-ignorelist-plugin';
 import { SERVER_GENERATED_EXTERNALS, getFeatureSupport, isZonelessApp } from './utils';
 import { createVirtualModulePlugin } from './virtual-module-plugin';
 import { createWasmPlugin } from './wasm-plugin';
+import { ExperimentalPlatform } from '../../builders/application/schema';
 
 export function createBrowserCodeBundleOptions(
   options: NormalizedApplicationBuildOptions,
@@ -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,
@@ -373,6 +378,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 +402,7 @@ export function createSsrEntryCodeBundleOptions(
         styleOptions,
       ),
     ],
-    inject: [ssrInjectRequireNamespace, ssrInjectManifestNamespace],
+    inject,
   };
 
   buildOptions.plugins ??= [];
@@ -490,9 +502,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'
+    );
   }
 
   /**