fix(@angular-devkit/build-angular): generate a file containing a list of prerendered routes

With this change when SSG is enabled a `prerendered-routes.json` file is emitted that contains all the prerendered routes.

This is useful for Cloud providers and other server engines to have server rules to serve these files as static.

Author: alan-agius4

packages/angular_devkit/build_angular/src/builders/application/execute-build.ts

@@ -198,25 +198,41 @@ export async function executeBuild(
   }
 
   // Perform i18n translation inlining if enabled
+  let prerenderedRoutes: string[];
+  let errors: string[];
+  let warnings: string[];
   if (i18nOptions.shouldInline) {
-    const { errors, warnings } = await inlineI18n(options, executionResult, initialFiles);
-    printWarningsAndErrorsToConsole(context, warnings, errors);
+    const result = await inlineI18n(options, executionResult, initialFiles);
+    errors = result.errors;
+    warnings = result.warnings;
+    prerenderedRoutes = result.prerenderedRoutes;
   } else {
-    const { errors, warnings, additionalAssets, additionalOutputFiles } =
-      await executePostBundleSteps(
-        options,
-        executionResult.outputFiles,
-        executionResult.assetFiles,
-        initialFiles,
-        // Set lang attribute to the defined source locale if present
-        i18nOptions.hasDefinedSourceLocale ? i18nOptions.sourceLocale : undefined,
-      );
+    const result = await executePostBundleSteps(
+      options,
+      executionResult.outputFiles,
+      executionResult.assetFiles,
+      initialFiles,
+      // Set lang attribute to the defined source locale if present
+      i18nOptions.hasDefinedSourceLocale ? i18nOptions.sourceLocale : undefined,
+    );
 
-    executionResult.outputFiles.push(...additionalOutputFiles);
-    executionResult.assetFiles.push(...additionalAssets);
-    printWarningsAndErrorsToConsole(context, warnings, errors);
+    errors = result.errors;
+    warnings = result.warnings;
+    prerenderedRoutes = result.prerenderedRoutes;
+    executionResult.outputFiles.push(...result.additionalOutputFiles);
+    executionResult.assetFiles.push(...result.additionalAssets);
   }
 
+  if (prerenderOptions) {
+    executionResult.addOutputFile(
+      'prerendered-routes.json',
+      JSON.stringify({ routes: prerenderedRoutes.sort((a, b) => a.localeCompare(b)) }, null, 2),
+      BuildOutputFileType.Root,
+    );
+  }
+
+  printWarningsAndErrorsToConsole(context, warnings, errors);
+
   logBuildStats(context, metafile, initialFiles, budgetFailures, estimatedTransferSizes);
 
   const buildTime = Number(process.hrtime.bigint() - startTime) / 10 ** 9;

packages/angular_devkit/build_angular/src/builders/application/execute-post-bundle.ts

@@ -39,11 +39,13 @@ export async function executePostBundleSteps(
   warnings: string[];
   additionalOutputFiles: BuildOutputFile[];
   additionalAssets: BuildOutputAsset[];
+  prerenderedRoutes: string[];
 }> {
   const additionalAssets: BuildOutputAsset[] = [];
   const additionalOutputFiles: BuildOutputFile[] = [];
   const allErrors: string[] = [];
   const allWarnings: string[] = [];
+  const prerenderedRoutes: string[] = [];
 
   const {
     serviceWorker,
@@ -105,7 +107,12 @@ export async function executePostBundleSteps(
       'The "index" option is required when using the "ssg" or "appShell" options.',
     );
 
-    const { output, warnings, errors } = await prerenderPages(
+    const {
+      output,
+      warnings,
+      errors,
+      prerenderedRoutes: generatedRoutes,
+    } = await prerenderPages(
       workspaceRoot,
       appShellOptions,
       prerenderOptions,
@@ -119,6 +126,7 @@ export async function executePostBundleSteps(
 
     allErrors.push(...errors);
     allWarnings.push(...warnings);
+    prerenderedRoutes.push(...Array.from(generatedRoutes));
 
     for (const [path, content] of Object.entries(output)) {
       additionalOutputFiles.push(
@@ -155,6 +163,7 @@ export async function executePostBundleSteps(
     errors: allErrors,
     warnings: allWarnings,
     additionalAssets,
+    prerenderedRoutes,
     additionalOutputFiles,
   };
 }

packages/angular_devkit/build_angular/src/builders/application/i18n.ts

@@ -7,7 +7,7 @@
  */
 
 import { BuilderContext } from '@angular-devkit/architect';
-import { join } from 'node:path';
+import { join, posix } from 'node:path';
 import { InitialFileRecord } from '../../tools/esbuild/bundler-context';
 import { ExecutionResult } from '../../tools/esbuild/bundler-execution-result';
 import { I18nInliner } from '../../tools/esbuild/i18n-inliner';
@@ -29,7 +29,7 @@ export async function inlineI18n(
   options: NormalizedApplicationBuildOptions,
   executionResult: ExecutionResult,
   initialFiles: Map<string, InitialFileRecord>,
-): Promise<{ errors: string[]; warnings: string[] }> {
+): Promise<{ errors: string[]; warnings: string[]; prerenderedRoutes: string[] }> {
   // Create the multi-threaded inliner with common options and the files generated from the build.
   const inliner = new I18nInliner(
     {
@@ -40,9 +40,10 @@ export async function inlineI18n(
     maxWorkers,
   );
 
-  const inlineResult: { errors: string[]; warnings: string[] } = {
+  const inlineResult: { errors: string[]; warnings: string[]; prerenderedRoutes: string[] } = {
     errors: [],
     warnings: [],
+    prerenderedRoutes: [],
   };
 
   // For each active locale, use the inliner to process the output files of the build.
@@ -59,17 +60,22 @@ export async function inlineI18n(
       const baseHref =
         getLocaleBaseHref(options.baseHref, options.i18nOptions, locale) ?? options.baseHref;
 
-      const { errors, warnings, additionalAssets, additionalOutputFiles } =
-        await executePostBundleSteps(
-          {
-            ...options,
-            baseHref,
-          },
-          localeOutputFiles,
-          executionResult.assetFiles,
-          initialFiles,
-          locale,
-        );
+      const {
+        errors,
+        warnings,
+        additionalAssets,
+        additionalOutputFiles,
+        prerenderedRoutes: generatedRoutes,
+      } = await executePostBundleSteps(
+        {
+          ...options,
+          baseHref,
+        },
+        localeOutputFiles,
+        executionResult.assetFiles,
+        initialFiles,
+        locale,
+      );
 
       localeOutputFiles.push(...additionalOutputFiles);
       inlineResult.errors.push(...errors);
@@ -87,7 +93,12 @@ export async function inlineI18n(
             destination: join(locale, assetFile.destination),
           });
         }
+
+        inlineResult.prerenderedRoutes.push(
+          ...generatedRoutes.map((route) => posix.join('/', locale, route)),
+        );
       } else {
+        inlineResult.prerenderedRoutes.push(...generatedRoutes);
         executionResult.assetFiles.push(...additionalAssets);
       }
 

packages/angular_devkit/build_angular/src/utils/server-rendering/prerender.ts

@@ -41,6 +41,7 @@ export async function prerenderPages(
   output: Record<string, string>;
   warnings: string[];
   errors: string[];
+  prerenderedRoutes: Set<string>;
 }> {
   const output: Record<string, string> = {};
   const warnings: string[] = [];
@@ -92,6 +93,7 @@ export async function prerenderPages(
       errors,
       warnings,
       output,
+      prerenderedRoutes: allRoutes,
     };
   }
 
@@ -114,7 +116,7 @@ export async function prerenderPages(
 
   try {
     const renderingPromises: Promise<void>[] = [];
-    const appShellRoute = appShellOptions.route && removeLeadingSlash(appShellOptions.route);
+    const appShellRoute = appShellOptions.route && addLeadingSlash(appShellOptions.route);
 
     for (const route of allRoutes) {
       const isAppShellRoute = appShellRoute === route;
@@ -123,7 +125,9 @@ export async function prerenderPages(
       const render: Promise<RenderResult> = renderWorker.run({ route, serverContext });
       const renderResult: Promise<void> = render.then(({ content, warnings, errors }) => {
         if (content !== undefined) {
-          const outPath = isAppShellRoute ? 'index.html' : posix.join(route, 'index.html');
+          const outPath = isAppShellRoute
+            ? 'index.html'
+            : removeLeadingSlash(posix.join(route, 'index.html'));
           output[outPath] = content;
         }
 
@@ -148,12 +152,13 @@ export async function prerenderPages(
     errors,
     warnings,
     output,
+    prerenderedRoutes: allRoutes,
   };
 }
 
 class RoutesSet extends Set<string> {
   override add(value: string): this {
-    return super.add(removeLeadingSlash(value));
+    return super.add(addLeadingSlash(value));
   }
 }
 
@@ -213,6 +218,10 @@ async function getAllRoutes(
   return { routes, warnings };
 }
 
+function addLeadingSlash(value: string): string {
+  return value.charAt(0) === '/' ? value : '/' + value;
+}
+
 function removeLeadingSlash(value: string): string {
   return value.charAt(0) === '/' ? value.slice(1) : value;
 }

tests/legacy-cli/e2e/tests/build/prerender/discover-routes-standalone.ts

@@ -1,9 +1,10 @@
 import { join } from 'path';
 import { getGlobalVariable } from '../../../utils/env';
-import { expectFileToMatch, rimraf, writeFile } from '../../../utils/fs';
+import { expectFileToMatch, readFile, rimraf, writeFile } from '../../../utils/fs';
 import { installWorkspacePackages } from '../../../utils/packages';
 import { ng } from '../../../utils/process';
 import { useSha } from '../../../utils/project';
+import { deepStrictEqual } from 'node:assert';
 
 export default async function () {
   const useWebpackBuilder = !getGlobalVariable('argv')['esbuild'];
@@ -111,5 +112,21 @@ export default async function () {
     for (const [filePath, fileMatch] of Object.entries(expects)) {
       await expectFileToMatch(join('dist/test-project/browser', filePath), fileMatch);
     }
+
+    if (!useWebpackBuilder) {
+      // prerendered-routes.json file is only generated when using esbuild.
+      const generatedRoutesStats = await readFile('dist/test-project/prerendered-routes.json');
+      deepStrictEqual(JSON.parse(generatedRoutesStats), {
+        routes: [
+          '/',
+          '/lazy-one',
+          '/lazy-one/lazy-one-child',
+          '/lazy-two',
+          '/two',
+          '/two/two-child-one',
+          '/two/two-child-two',
+        ],
+      });
+    }
   }
 }