feat(@angular/build): add prerender.format option to prerender routes as <route>.html

The new `format` property of the `prerender` option accepts `directory` (default, unchanged
behavior) and `file`, like the `build.format` option of Astro. With `file`, routes are written
to `<route>.html` instead of `<route>/index.html`. Static hosts serve `<route>/index.html` under
`/<route>/`, so a request to `/<route>` is first redirected to the URL with a trailing slash,
which the Angular router then removes again. Hosts that serve `<route>.html` for `/<route>`
respond without that redirect.

The root route (after removing the `baseHref` option) is still written to `index.html`. Static
redirect pages follow the same layout. `prerender.format` is also considered when `outputMode`
is set, while `prerender.routesFile` and `prerender.discoverRoutes` are not.

`file` is only considered when the build does not produce a server, because the `@angular/ssr`
runtime looks up prerendered pages as `<route>/index.html`. In that case, a warning is reported
and routes are written to `<route>/index.html`.

Closes #29173

Author: JohannesHoppe

goldens/public-api/angular/build/index.api.md

@@ -55,6 +55,7 @@ export type ApplicationBuilderOptions = {
     poll?: number;
     polyfills?: string[];
     prerender?: PrerenderUnion;
+    prerenderFormat?: PrerenderFormat;
     preserveSymlinks?: boolean;
     progress?: boolean;
     scripts?: ScriptElement[];

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

@@ -71,6 +71,7 @@ export async function executePostBundleSteps(
     outputMode,
     serverEntryPoint,
     prerenderOptions,
+    prerenderFormat,
     appShellOptions,
     publicPath,
     workspaceRoot,
@@ -168,6 +169,8 @@ export async function executePostBundleSteps(
       [...outputFiles, ...additionalOutputFiles],
       assetFiles,
       outputMode,
+      prerenderFormat,
+      indexHtmlOptions.output,
       sourcemapOptions.scripts,
       maxWorkers,
     );

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

@@ -32,6 +32,7 @@ import {
   OutputMode,
   OutputPathClass,
   Platform,
+  PrerenderFormat,
 } from './schema';
 
 /**
@@ -342,6 +343,20 @@ export async function normalizeOptions(
       options.outputMode === OutputMode.Static,
   };
 
+  let prerenderFormat = options.prerenderFormat ?? PrerenderFormat.Directory;
+  if (prerenderFormat === PrerenderFormat.File && !outputOptions.ignoreServer) {
+    // The server runtime of '@angular/ssr' looks up prerendered pages as '<route>/index.html'.
+    // The warning is only relevant when pages are actually prerendered, which the dev-server skips.
+    if ((prerenderOptions || appShellOptions) && !(options.partialSSRBuild || usePartialSsrBuild)) {
+      context.logger.warn(
+        'The "prerenderFormat" option set to "file" is not considered when the build produces a ' +
+          'server ("outputMode" set to "server", or "ssr" without "outputMode").',
+      );
+    }
+
+    prerenderFormat = PrerenderFormat.Directory;
+  }
+
   const outputNames = {
     bundles:
       options.outputHashing === OutputHashing.All || options.outputHashing === OutputHashing.Bundles
@@ -492,6 +507,7 @@ export async function normalizeOptions(
     subresourceIntegrity,
     serverEntryPoint,
     prerenderOptions,
+    prerenderFormat,
     appShellOptions,
     outputMode,
     ssrOptions,

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

@@ -587,6 +587,12 @@
         }
       ]
     },
+    "prerenderFormat": {
+      "type": "string",
+      "description": "Defines the file layout of prerendered (SSG) pages. 'directory': '/foo' is written to 'foo/index.html'. 'file': '/foo' is written to 'foo.html', which some hosting services serve for '/foo' without a redirect to '/foo/'. The root route of the application and of each locale is always written to 'index.html'. Routes that cannot be written safely to '<route>.html' keep '<route>/index.html' with a warning. Only considered when the build does not produce a server.",
+      "enum": ["directory", "file"],
+      "default": "directory"
+    },
     "ssr": {
       "description": "Server side render (SSR) pages of your application during runtime.",
       "default": false,