feat(@angular/ssr): add modulepreload for lazy-loaded routes

Enhance performance when using SSR by adding `modulepreload` links to lazy-loaded routes. This ensures that the required modules are preloaded in the background, improving the user experience and reducing the time to interactive.

Closes #26484

Author: alan-agius4

packages/angular/build/BUILD.bazel

@@ -127,6 +127,7 @@ ts_library(
         "@npm//@angular/compiler-cli",
         "@npm//@babel/core",
         "@npm//prettier",
+        "@npm//typescript",
     ],
 )
 

packages/angular/build/src/builders/application/execute-build.ts

@@ -247,12 +247,13 @@ export async function executeBuild(
 
   // Perform i18n translation inlining if enabled
   if (i18nOptions.shouldInline) {
-    const result = await inlineI18n(options, executionResult, initialFiles);
+    const result = await inlineI18n(metafile, options, executionResult, initialFiles);
     executionResult.addErrors(result.errors);
     executionResult.addWarnings(result.warnings);
     executionResult.addPrerenderedRoutes(result.prerenderedRoutes);
   } else {
     const result = await executePostBundleSteps(
+      metafile,
       options,
       executionResult.outputFiles,
       executionResult.assetFiles,

packages/angular/build/src/builders/application/execute-post-bundle.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import type { Metafile } from 'esbuild';
 import assert from 'node:assert';
 import {
   BuildOutputFile,
@@ -34,6 +35,7 @@ import { OutputMode } from './schema';
 
 /**
  * Run additional builds steps including SSG, AppShell, Index HTML file and Service worker generation.
+ * @param metafile An esbuild metafile object.
  * @param options The normalized application builder options used to create the build.
  * @param outputFiles The output files of an executed build.
  * @param assetFiles The assets of an executed build.
@@ -42,6 +44,7 @@ import { OutputMode } from './schema';
  */
 // eslint-disable-next-line max-lines-per-function
 export async function executePostBundleSteps(
+  metafile: Metafile,
   options: NormalizedApplicationBuildOptions,
   outputFiles: BuildOutputFile[],
   assetFiles: BuildOutputAsset[],
@@ -71,6 +74,7 @@ export async function executePostBundleSteps(
     serverEntryPoint,
     prerenderOptions,
     appShellOptions,
+    publicPath,
     workspaceRoot,
     partialSSRBuild,
   } = options;
@@ -108,6 +112,7 @@ export async function executePostBundleSteps(
   }
 
   // Create server manifest
+  const initialFilesPaths = new Set(initialFiles.keys());
   if (serverEntryPoint) {
     const { manifestContent, serverAssetsChunks } = generateAngularServerAppManifest(
       additionalHtmlOutputFiles,
@@ -116,6 +121,9 @@ export async function executePostBundleSteps(
       undefined,
       locale,
       baseHref,
+      initialFilesPaths,
+      metafile,
+      publicPath,
     );
 
     additionalOutputFiles.push(
@@ -197,6 +205,9 @@ export async function executePostBundleSteps(
         serializableRouteTreeNodeForManifest,
         locale,
         baseHref,
+        initialFilesPaths,
+        metafile,
+        publicPath,
       );
 
       for (const chunk of serverAssetsChunks) {

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

@@ -7,6 +7,7 @@
  */
 
 import { BuilderContext } from '@angular-devkit/architect';
+import type { Metafile } from 'esbuild';
 import { join } from 'node:path';
 import { BuildOutputFileType, InitialFileRecord } from '../../tools/esbuild/bundler-context';
 import {
@@ -23,11 +24,13 @@ import { NormalizedApplicationBuildOptions, getLocaleBaseHref } from './options'
 /**
  * Inlines all active locales as specified by the application build options into all
  * application JavaScript files created during the build.
+ * @param metafile An esbuild metafile object.
  * @param options The normalized application builder options used to create the build.
  * @param executionResult The result of an executed build.
  * @param initialFiles A map containing initial file information for the executed build.
  */
 export async function inlineI18n(
+  metafile: Metafile,
   options: NormalizedApplicationBuildOptions,
   executionResult: ExecutionResult,
   initialFiles: Map<string, InitialFileRecord>,
@@ -80,6 +83,7 @@ export async function inlineI18n(
         additionalOutputFiles,
         prerenderedRoutes: generatedRoutes,
       } = await executePostBundleSteps(
+        metafile,
         {
           ...options,
           baseHref,

packages/angular/build/src/tools/angular/compilation/aot-compilation.ts

@@ -17,6 +17,7 @@ import {
   ensureSourceFileVersions,
 } from '../angular-host';
 import { replaceBootstrap } from '../transformers/jit-bootstrap-transformer';
+import { lazyRoutesTransformer } from '../transformers/lazy-routes-transformer';
 import { createWorkerTransformer } from '../transformers/web-worker-transformer';
 import { AngularCompilation, DiagnosticModes, EmitFileResult } from './angular-compilation';
 import { collectHmrCandidates } from './hmr-candidates';
@@ -47,6 +48,10 @@ class AngularCompilationState {
 export class AotCompilation extends AngularCompilation {
   #state?: AngularCompilationState;
 
+  constructor(private readonly browserOnlyBuild: boolean) {
+    super();
+  }
+
   async initialize(
     tsconfig: string,
     hostOptions: AngularHostOptions,
@@ -300,8 +305,12 @@ export class AotCompilation extends AngularCompilation {
     transformers.before ??= [];
     transformers.before.push(
       replaceBootstrap(() => typeScriptProgram.getProgram().getTypeChecker()),
+      webWorkerTransform,
     );
-    transformers.before.push(webWorkerTransform);
+
+    if (!this.browserOnlyBuild) {
+      transformers.before.push(lazyRoutesTransformer(compilerOptions, compilerHost));
+    }
 
     // Emit is handled in write file callback when using TypeScript
     if (useTypeScriptTranspilation) {

packages/angular/build/src/tools/angular/compilation/factory.ts

@@ -14,22 +14,26 @@ import type { AngularCompilation } from './angular-compilation';
  * compilation either for AOT or JIT mode. By default a parallel compilation is created
  * that uses a Node.js worker thread.
  * @param jit True, for Angular JIT compilation; False, for Angular AOT compilation.
+ * @param browserOnlyBuild True, for browser only builds; False, for browser and server builds.
  * @returns An instance of an Angular compilation object.
  */
-export async function createAngularCompilation(jit: boolean): Promise<AngularCompilation> {
+export async function createAngularCompilation(
+  jit: boolean,
+  browserOnlyBuild: boolean,
+): Promise<AngularCompilation> {
   if (useParallelTs) {
     const { ParallelCompilation } = await import('./parallel-compilation');
 
-    return new ParallelCompilation(jit);
+    return new ParallelCompilation(jit, browserOnlyBuild);
   }
 
   if (jit) {
     const { JitCompilation } = await import('./jit-compilation');
 
-    return new JitCompilation();
+    return new JitCompilation(browserOnlyBuild);
   } else {
     const { AotCompilation } = await import('./aot-compilation');
 
-    return new AotCompilation();
+    return new AotCompilation(browserOnlyBuild);
   }
 }

packages/angular/build/src/tools/angular/compilation/jit-compilation.ts

@@ -13,6 +13,7 @@ import { loadEsmModule } from '../../../utils/load-esm';
 import { profileSync } from '../../esbuild/profiling';
 import { AngularHostOptions, createAngularCompilerHost } from '../angular-host';
 import { createJitResourceTransformer } from '../transformers/jit-resource-transformer';
+import { lazyRoutesTransformer } from '../transformers/lazy-routes-transformer';
 import { createWorkerTransformer } from '../transformers/web-worker-transformer';
 import { AngularCompilation, DiagnosticModes, EmitFileResult } from './angular-compilation';
 
@@ -29,6 +30,10 @@ class JitCompilationState {
 export class JitCompilation extends AngularCompilation {
   #state?: JitCompilationState;
 
+  constructor(private readonly browserOnlyBuild: boolean) {
+    super();
+  }
+
   async initialize(
     tsconfig: string,
     hostOptions: AngularHostOptions,
@@ -116,8 +121,8 @@ export class JitCompilation extends AngularCompilation {
       replaceResourcesTransform,
       webWorkerTransform,
     } = this.#state;
-    const buildInfoFilename =
-      typeScriptProgram.getCompilerOptions().tsBuildInfoFile ?? '.tsbuildinfo';
+    const compilerOptions = typeScriptProgram.getCompilerOptions();
+    const buildInfoFilename = compilerOptions.tsBuildInfoFile ?? '.tsbuildinfo';
 
     const emittedFiles: EmitFileResult[] = [];
     const writeFileCallback: ts.WriteFileCallback = (filename, contents, _a, _b, sourceFiles) => {
@@ -140,6 +145,10 @@ export class JitCompilation extends AngularCompilation {
       ],
     };
 
+    if (!this.browserOnlyBuild) {
+      transformers.before.push(lazyRoutesTransformer(compilerOptions, compilerHost));
+    }
+
     // TypeScript will loop until there are no more affected files in the program
     while (
       typeScriptProgram.emitNextAffectedFile(writeFileCallback, undefined, undefined, transformers)

packages/angular/build/src/tools/angular/compilation/parallel-compilation.ts

@@ -26,7 +26,10 @@ import { AngularCompilation, DiagnosticModes, EmitFileResult } from './angular-c
 export class ParallelCompilation extends AngularCompilation {
   readonly #worker: WorkerPool;
 
-  constructor(readonly jit: boolean) {
+  constructor(
+    private readonly jit: boolean,
+    private readonly browserOnlyBuild: boolean,
+  ) {
     super();
 
     // TODO: Convert to import.meta usage during ESM transition
@@ -99,6 +102,7 @@ export class ParallelCompilation extends AngularCompilation {
         fileReplacements: hostOptions.fileReplacements,
         tsconfig,
         jit: this.jit,
+        browserOnlyBuild: this.browserOnlyBuild,
         stylesheetPort: stylesheetChannel.port2,
         optionsPort: optionsChannel.port2,
         optionsSignal,

packages/angular/build/src/tools/angular/compilation/parallel-worker.ts

@@ -17,6 +17,7 @@ import { JitCompilation } from './jit-compilation';
 
 export interface InitRequest {
   jit: boolean;
+  browserOnlyBuild: boolean;
   tsconfig: string;
   fileReplacements?: Record<string, string>;
   stylesheetPort: MessagePort;
@@ -31,7 +32,9 @@ let compilation: AngularCompilation | undefined;
 const sourceFileCache = new SourceFileCache();
 
 export async function initialize(request: InitRequest) {
-  compilation ??= request.jit ? new JitCompilation() : new AotCompilation();
+  compilation ??= request.jit
+    ? new JitCompilation(request.browserOnlyBuild)
+    : new AotCompilation(request.browserOnlyBuild);
 
   const stylesheetRequests = new Map<string, [(value: string) => void, (reason: Error) => void]>();
   request.stylesheetPort.on('message', ({ requestId, value, error }) => {

packages/angular/build/src/tools/angular/transformers/lazy-routes-transformer.ts

@@ -0,0 +1,130 @@
+/**
+ * @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 assert from 'node:assert';
+import { relative } from 'node:path/posix';
+import ts from 'typescript';
+
+export function lazyRoutesTransformer(
+  compilerOptions: ts.CompilerOptions,
+  compilerHost: ts.CompilerHost,
+): ts.TransformerFactory<ts.SourceFile> {
+  const moduleResolutionCache = compilerHost.getModuleResolutionCache?.();
+  assert(
+    typeof compilerOptions.basePath === 'string',
+    'compilerOptions.basePath should be a string.',
+  );
+  const basePath = compilerOptions.basePath;
+
+  return (context: ts.TransformationContext) => {
+    const factory = context.factory;
+
+    const visitor = (node: ts.Node): ts.Node => {
+      if (!ts.isObjectLiteralExpression(node)) {
+        return ts.visitEachChild(node, visitor, context);
+      }
+
+      let hasPathProperty = false;
+      let loadComponentOrChildrenProperty: ts.PropertyAssignment | undefined;
+      for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) {
+          continue;
+        }
+
+        const propertyNameText = prop.name.text;
+        if (propertyNameText === 'path') {
+          hasPathProperty = true;
+        } else if (propertyNameText === 'loadComponent' || propertyNameText === 'loadChildren') {
+          loadComponentOrChildrenProperty = prop;
+        }
+
+        if (hasPathProperty && loadComponentOrChildrenProperty) {
+          break;
+        }
+      }
+
+      const initializer = loadComponentOrChildrenProperty?.initializer;
+      if (
+        !hasPathProperty ||
+        !initializer ||
+        !ts.isArrowFunction(initializer) ||
+        !ts.isCallExpression(initializer.body) ||
+        !ts.isPropertyAccessExpression(initializer.body.expression) ||
+        initializer.body.expression.name.text !== 'then' ||
+        !ts.isCallExpression(initializer.body.expression.expression) ||
+        initializer.body.expression.expression.expression.kind !== ts.SyntaxKind.ImportKeyword
+      ) {
+        return ts.visitEachChild(node, visitor, context);
+      }
+
+      const callExpressionArgument = initializer.body.expression.expression.arguments[0];
+      if (
+        !ts.isStringLiteral(callExpressionArgument) &&
+        !ts.isNoSubstitutionTemplateLiteral(callExpressionArgument)
+      ) {
+        return ts.visitEachChild(node, visitor, context);
+      }
+
+      const resolvedPath = ts.resolveModuleName(
+        callExpressionArgument.text,
+        node.getSourceFile().fileName,
+        compilerOptions,
+        compilerHost,
+        moduleResolutionCache,
+      )?.resolvedModule?.resolvedFileName;
+
+      if (!resolvedPath) {
+        return ts.visitEachChild(node, visitor, context);
+      }
+
+      const resolvedRelativePath = relative(basePath, resolvedPath);
+
+      // Create the new property
+      // Exmaple: `...(typeof ngServerMode !== "undefined" && ngServerMode ? { ɵentryName: "src/home.ts" } : undefined)`
+      const newProperty = factory.createSpreadAssignment(
+        factory.createParenthesizedExpression(
+          factory.createConditionalExpression(
+            factory.createBinaryExpression(
+              factory.createBinaryExpression(
+                factory.createTypeOfExpression(factory.createIdentifier('ngServerMode')),
+                factory.createToken(ts.SyntaxKind.ExclamationEqualsEqualsToken),
+                factory.createStringLiteral('undefined'),
+              ),
+              factory.createToken(ts.SyntaxKind.AmpersandAmpersandToken),
+              factory.createIdentifier('ngServerMode'),
+            ),
+            factory.createToken(ts.SyntaxKind.QuestionToken),
+            factory.createObjectLiteralExpression(
+              [
+                factory.createPropertyAssignment(
+                  factory.createIdentifier('ɵentryName'),
+                  factory.createStringLiteral(resolvedRelativePath),
+                ),
+              ],
+              false,
+            ),
+            factory.createToken(ts.SyntaxKind.ColonToken),
+            factory.createIdentifier('undefined'),
+          ),
+        ),
+      );
+
+      return factory.updateObjectLiteralExpression(node, [...node.properties, newProperty]);
+    };
+
+    return (sourceFile) => {
+      const text = sourceFile.text;
+      if (!text.includes('loadC')) {
+        // Fast check for 'loadComponent' and 'loadChildren'.
+        return sourceFile;
+      }
+
+      return ts.visitEachChild(sourceFile, visitor, context);
+    };
+  };
+}