@angular-schule/prerender-format 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Angular.Schule (by Johannes Hoppe)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# @angular-schule/prerender-format
+
+[![NPM version][npm-image]][npm-url]
+[![GitHub Actions](https://github.com/angular-schule/prerender-format/actions/workflows/main.yml/badge.svg)](https://github.com/angular-schule/prerender-format/actions/workflows/main.yml)
+[![The MIT License](https://img.shields.io/badge/license-MIT-orange.svg?color=blue&style=flat-square)](http://opensource.org/licenses/MIT)
+
+**Nice looking URLs and flawless SEO for your prerendered Angular app: `about.html` instead of `about/index.html`, no more trailing slash redirects! 🚀**
+
+**Table of contents:**
+
+1. [💡 Why?](#why)
+2. [⚠️ Prerequisites](#prerequisites)
+3. [🚀 Quick Start](#quickstart)
+4. [⚙️ Installation](#installation)
+5. [📦 Options](#options)
+6. [🔭 Other frameworks](#other-frameworks)
+7. [🌍 Hosts](#hosts)
+8. [🔧 How it works](#how-it-works)
+9. [📁 Known limitations](#limitations)
+10. [🏁 License](#license)
+
+<hr>
+
+## 💡 Why? <a name="why"></a>
+
+### Today: nice URLs or good SEO, you can't have both
+
+Angular's prerendering (SSG) writes every route into its own folder: the route `blog/my-article` becomes `blog/my-article/index.html`.
+Static hosts see a folder and redirect `/blog/my-article` to `/blog/my-article/`.
+So you have to choose:
+
+- **Nice looking URLs, but redirects:** links, canonical tags and sitemap have to use `/blog/my-article`. Every direct visit (search engine, bookmark, shared link) starts with a 301/308 redirect to `/blog/my-article/`, and the Angular router then removes the trailing slash again.
+- **No redirects, but trailing slashes everywhere:** links, canonical tags and sitemap have to use `/blog/my-article/`. Pages answer with 200, but every URL ends with a slash, and Angular needs an extra provider to keep it in the address bar: `{ provide: LocationStrategy, useClass: TrailingSlashPathLocationStrategy }` (see [`TrailingSlashPathLocationStrategy`](https://angular.dev/api/common/TrailingSlashPathLocationStrategy)).
+
+### With this builder: nice URLs and good SEO, we deserve both!
+
+The same route becomes `blog/my-article.html`, and hosts like Cloudflare Pages serve it under `/blog/my-article` directly, with status 200.
+
+- **Nice looking URLs:** `/blog/my-article`, without a trailing slash, in links, in the address bar and in the server response alike.
+- **Flawless SEO:** every page answers directly with 200. Search engines see no redirect, and the URL they crawl is the same one your canonical tag, hreflang links and sitemap point to.
+- **Old links keep working:** addresses with a trailing slash redirect to the address without it (measured on Cloudflare Pages, see [Hosts](#hosts)).
+
+This is the option proposed in [angular/angular-cli#29173](https://github.com/angular/angular-cli/issues/29173).
+The builder is a stopgap: developed and tested for Angular 22, until Angular has a built-in option and this package is no longer needed.
+
+## ⚠️ Prerequisites <a name="prerequisites"></a>
+
+- Angular 22 with the application builder (`@angular/build:application`)
+- `"outputMode": "static"`
+- A host that serves `foo.html` under `/foo` without a redirect (see [Hosts](#hosts))
+
+## 🚀 Quick Start <a name="quickstart"></a>
+
+```sh
+ng add @angular-schule/prerender-format
+ng build
+```
+
+## ⚙️ Installation <a name="installation"></a>
+
+`ng add @angular-schule/prerender-format` installs the package and changes the builder of your build target in `angular.json` and sets `prerenderFormat`.
+Your build must already use `"outputMode": "static"`: if the build target (or one of its configurations) ships an SSR server, `ng add` stops and tells you so.
+
+```json
+"build": {
+  "builder": "@angular-schule/prerender-format:application",
+  "options": {
+    "outputMode": "static",
+    "prerenderFormat": "file"
+  }
+}
+```
+
+All other options stay as they are: the builder accepts every option of `@angular/build:application` and passes it on.
+Use `--project` to choose the project in a workspace with several projects.
+
+## 📦 Options <a name="options"></a>
+
+#### prerenderFormat
+
+- **optional**
+- Default: `directory`
+
+| `prerenderFormat` | Route `blog/my-article` | Start page |
+|---|---|---|
+| `directory` | `blog/my-article/index.html` | `index.html` |
+| `file` | `blog/my-article.html` | `index.html` |
+
+The name and the values follow Astro's [`build.format`](#other-frameworks).
+
+Parent and child routes live side by side: `blog.html` next to the folder `blog/`.
+The start page of each locale (for example with base href `/en/`) stays `index.html`.
+
+A route whose last segment is `index` (`/index`, `/docs/index`) fails the build with a clear message: as `index.html` it would be served under the parent path, and `/index` would overwrite the start page.
+
+## 🔭 Other frameworks <a name="other-frameworks"></a>
+
+Static site generators have offered this choice for a long time. We decided to borrow the terminology from Astro: `build.format` with `'directory'` and `'file'` became `prerenderFormat` with the same values.
+
+| Framework | Option | `about/index.html` | `about.html` |
+|---|---|---|---|
+| **Astro** | `build.format` | `'directory'` (default) | `'file'` |
+| Next.js (static export) | `trailingSlash` | `true` | `false` (default) |
+| SvelteKit | `trailingSlash` | `'always'` | `'never'` (default) |
+| Nuxt 2 | `generate.subFolders` | `true` (default) | `false` |
+| Hugo | `uglyURLs` | `false` (default) | `true` |
+| **Angular** | **NEW: `prerenderFormat`** | **`'directory'` (default)** | **`'file'`** |
+
+Astro's documentation recommends `build.format: 'file'` together with `trailingSlash: 'never'`, which is exactly the combination this builder enables for Angular.
+
+## 🌍 Hosts <a name="hosts"></a>
+
+Measured on **Cloudflare Pages** with `prerenderFormat: "file"`:
+
+| Request | Response |
+|---|---|
+| `/foo` | 200, `foo.html` |
+| `/foo/` | 308 → `/foo` |
+| `/foo.html` | 308 → `/foo` |
+| `/foo` with `foo.html` next to the folder `foo/` | 200, `foo.html` |
+
+Old addresses with a trailing slash keep working, they redirect to the address without it.
+
+GitHub Pages, Firebase Hosting, Vercel and Netlify are listed in the Angular issue as supporting this, some of them behind a setting.
+Check your host before switching.
+
+## 🔧 How it works <a name="how-it-works"></a>
+
+The builder calls `buildApplication` from `@angular/build` and wraps its internal `prerenderPages()` function, which returns the prerendered pages as a record of output paths.
+The wrapper renames `foo/index.html` to `foo.html` before anything is written, so the service worker manifest and all later build steps see the final file names.
+
+`prerenderPages()` is internal API, so this package supports Angular 22 only.
+After a successful build, the builder checks that the prerendered pages actually went through the wrapper, and fails otherwise.
+
+## 📁 Known limitations <a name="limitations"></a>
+
+- **Static builds only, by design.** `prerenderFormat: "file"` solves a problem of static hosting and makes no sense in other setups. An `ssr` entry is fine as long as `"outputMode"` is `"static"`: Angular then uses it only during `ng build` to prerender the pages, and no server is deployed. If a server is deployed, the build fails: a server needs no `.html` files, it answers `/foo` directly without redirecting to `/foo/`, and the Angular SSR server looks up prerendered pages as `index.html`.
+
+  ✅ Works: static output, the `ssr` entry only renders at build time
+
+  ```json
+  "options": {
+    "outputMode": "static",
+    "server": "src/main.server.ts",
+    "ssr": { "entry": "src/server.ts" },
+    "prerenderFormat": "file"
+  }
+  ```
+
+  ✅ Works: prerendering without SSR
+
+  ```json
+  "options": {
+    "server": "src/main.server.ts",
+    "prerender": true,
+    "prerenderFormat": "file"
+  }
+  ```
+
+  ❌ Fails: a server is deployed
+
+  ```json
+  "options": {
+    "outputMode": "server",
+    "server": "src/main.server.ts",
+    "ssr": { "entry": "src/server.ts" },
+    "prerenderFormat": "file"
+  }
+  ```
+
+  ❌ Fails: SSR without `outputMode` also deploys a server
+
+  ```json
+  "options": {
+    "server": "src/main.server.ts",
+    "ssr": { "entry": "src/server.ts" },
+    "prerenderFormat": "file"
+  }
+  ```
+
+- **`ng test` warning.** The `@angular/build:unit-test` builder logs a warning when its `buildTarget` uses a builder other than `@angular/build:application`. Tests run normally.
+
+## 🏁 License <a name="license"></a>
+
+Code released under the [MIT license](LICENSE).
+
+[npm-url]: https://www.npmjs.com/package/@angular-schule/prerender-format
+[npm-image]: https://badge.fury.io/js/@angular-schule%2Fprerender-format.svg

package/application/builder.d.ts

@@ -0,0 +1,9 @@
+import { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
+import { ApplicationBuilderOptions } from '@angular/build';
+export type PrerenderFormat = 'directory' | 'file';
+export interface Schema extends ApplicationBuilderOptions {
+    prerenderFormat?: PrerenderFormat;
+}
+export declare function executeBuild(options: Schema, context: BuilderContext): AsyncIterable<BuilderOutput>;
+declare const _default: import("@angular-devkit/architect").Builder<Schema & import("@angular-devkit/core").JsonObject>;
+export default _default;

package/application/builder.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeBuild = executeBuild;
+const architect_1 = require("@angular-devkit/architect");
+const build_1 = require("@angular/build");
+const path = __importStar(require("path"));
+const file_format_1 = require("./file-format");
+const ships_server_1 = require("./ships-server");
+async function* executeBuild(options, context) {
+    const { prerenderFormat = 'directory', ...applicationOptions } = options;
+    if (prerenderFormat !== 'file') {
+        yield* (0, build_1.buildApplication)(applicationOptions, context);
+        return;
+    }
+    if ((0, ships_server_1.shipsServer)(applicationOptions)) {
+        context.logger.error(`❌ 'prerenderFormat: "file"' requires 'outputMode: "static"': ` +
+            `the Angular SSR server looks up prerendered pages as 'index.html'.`);
+        yield { success: false };
+        return;
+    }
+    try {
+        (0, file_format_1.installFileFormat)(path.dirname(require.resolve('@angular/build/package.json')));
+    }
+    catch (e) {
+        context.logger.error('❌ ' + (e instanceof Error ? e.message : String(e)));
+        yield { success: false };
+        return;
+    }
+    let callsBefore = (0, file_format_1.getPrerenderCalls)();
+    for await (const result of (0, build_1.buildApplication)(applicationOptions, context)) {
+        const calls = (0, file_format_1.getPrerenderCalls)();
+        if (result.success && calls === callsBefore) {
+            context.logger.error(`❌ 'prerenderFormat: "file"' had no effect: no pages were prerendered through @angular-schule/prerender-format. ` +
+                `Check that prerendering is enabled ('outputMode: "static"' with server routes, or 'prerender'). ` +
+                `If it is, this version of @angular/build is not supported.`);
+            yield { ...result, success: false };
+        }
+        else {
+            yield result;
+        }
+        callsBefore = calls;
+    }
+}
+exports.default = (0, architect_1.createBuilder)(executeBuild);
+//# sourceMappingURL=builder.js.map

package/application/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../application/builder.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,oCAgDC;AAvED,yDAAyF;AACzF,0CAA6E;AAC7E,2CAA6B;AAE7B,+CAAqE;AACrE,iDAA6C;AAkBtC,KAAK,SAAS,CAAC,CAAC,YAAY,CACjC,OAAe,EACf,OAAuB;IAEvB,MAAM,EAAE,eAAe,GAAG,WAAW,EAAE,GAAG,kBAAkB,EAAE,GAAG,OAAO,CAAC;IAEzE,IAAI,eAAe,KAAK,MAAM,EAAE,CAAC;QAC/B,KAAK,CAAC,CAAC,IAAA,wBAAgB,EAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAErD,OAAO;IACT,CAAC;IAED,IAAI,IAAA,0BAAW,EAAC,kBAAkB,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+DAA+D;YAC7D,oEAAoE,CACvE,CAAC;QACF,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAEzB,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,IAAA,+BAAiB,EAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,6BAA6B,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAEzB,OAAO;IACT,CAAC;IAID,IAAI,WAAW,GAAG,IAAA,+BAAiB,GAAE,CAAC;IACtC,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,IAAA,wBAAgB,EAAC,kBAAkB,EAAE,OAAO,CAAC,EAAE,CAAC;QACzE,MAAM,KAAK,GAAG,IAAA,+BAAiB,GAAE,CAAC;QAClC,IAAI,MAAM,CAAC,OAAO,IAAI,KAAK,KAAK,WAAW,EAAE,CAAC;YAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iHAAiH;gBAC/G,kGAAkG;gBAClG,4DAA4D,CAC/D,CAAC;YACF,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,CAAC;QACf,CAAC;QACD,WAAW,GAAG,KAAK,CAAC;IACtB,CAAC;AACH,CAAC;AAED,kBAAe,IAAA,yBAAa,EAAS,YAAY,CAAC,CAAC","sourcesContent":["import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';\nimport { ApplicationBuilderOptions, buildApplication } from '@angular/build';\nimport * as path from 'path';\n\nimport { getPrerenderCalls, installFileFormat } from './file-format';\nimport { shipsServer } from './ships-server';\n\nexport type PrerenderFormat = 'directory' | 'file';\n\nexport interface Schema extends ApplicationBuilderOptions {\n  /**\n   * File layout of prerendered routes.\n   * - `directory` (default): `foo/index.html`\n   * - `file`: `foo.html`, the start page stays `index.html`\n   */\n  prerenderFormat?: PrerenderFormat;\n}\n\n/**\n * Runs `@angular/build:application` and, with `prerenderFormat: \"file\"`,\n * writes prerendered routes as `foo.html` instead of `foo/index.html`.\n * Exported separately for testing purposes.\n */\nexport async function* executeBuild(\n  options: Schema,\n  context: BuilderContext\n): AsyncIterable<BuilderOutput> {\n  const { prerenderFormat = 'directory', ...applicationOptions } = options;\n\n  if (prerenderFormat !== 'file') {\n    yield* buildApplication(applicationOptions, context);\n\n    return;\n  }\n\n  if (shipsServer(applicationOptions)) {\n    context.logger.error(\n      `❌ 'prerenderFormat: \"file\"' requires 'outputMode: \"static\"': ` +\n        `the Angular SSR server looks up prerendered pages as 'index.html'.`\n    );\n    yield { success: false };\n\n    return;\n  }\n\n  try {\n    installFileFormat(path.dirname(require.resolve('@angular/build/package.json')));\n  } catch (e) {\n    context.logger.error('❌ ' + (e instanceof Error ? e.message : String(e)));\n    yield { success: false };\n\n    return;\n  }\n\n  // Every successful build must have passed its prerendered pages through the wrapper.\n  // Otherwise nothing was prerendered, or @angular/build no longer calls the wrapped function.\n  let callsBefore = getPrerenderCalls();\n  for await (const result of buildApplication(applicationOptions, context)) {\n    const calls = getPrerenderCalls();\n    if (result.success && calls === callsBefore) {\n      context.logger.error(\n        `❌ 'prerenderFormat: \"file\"' had no effect: no pages were prerendered through @angular-schule/prerender-format. ` +\n          `Check that prerendering is enabled ('outputMode: \"static\"' with server routes, or 'prerender'). ` +\n          `If it is, this version of @angular/build is not supported.`\n      );\n      yield { ...result, success: false };\n    } else {\n      yield result;\n    }\n    callsBefore = calls;\n  }\n}\n\nexport default createBuilder<Schema>(executeBuild);\n"]}

package/application/file-format.d.ts

@@ -0,0 +1,20 @@
+export interface PrerenderedFile {
+    content: string;
+    appShellRoute: boolean;
+}
+export type PrerenderOutput = Record<string, PrerenderedFile>;
+export interface PrerenderResult {
+    output: PrerenderOutput;
+    errors?: string[];
+    [key: string]: unknown;
+}
+export type PrerenderPages = (...args: unknown[]) => Promise<PrerenderResult>;
+export interface FileOutputResult {
+    output: PrerenderOutput;
+    errors: string[];
+}
+export declare function getPrerenderCalls(): number;
+export declare function toFilePath(outPath: string): string;
+export declare function toFileOutput(output: PrerenderOutput): FileOutputResult;
+export declare function wrapPrerenderPages(prerenderPages: PrerenderPages): PrerenderPages;
+export declare function installFileFormat(angularBuildRoot: string): void;

package/application/file-format.js

@@ -0,0 +1,124 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPrerenderCalls = getPrerenderCalls;
+exports.toFilePath = toFilePath;
+exports.toFileOutput = toFileOutput;
+exports.wrapPrerenderPages = wrapPrerenderPages;
+exports.installFileFormat = installFileFormat;
+const path = __importStar(require("path"));
+const INDEX_FILE = 'index.html';
+const INDEX_SUFFIX = '/' + INDEX_FILE;
+const PATCHED = Symbol.for('@angular-schule/prerender-format:patched');
+const PRERENDER_MODULE = 'src/utils/server-rendering/prerender.js';
+let prerenderCalls = 0;
+function getPrerenderCalls() {
+    return prerenderCalls;
+}
+function toFilePath(outPath) {
+    if (!outPath.endsWith(INDEX_SUFFIX)) {
+        return outPath;
+    }
+    return outPath.slice(0, -INDEX_SUFFIX.length) + '.html';
+}
+function routeOf(outPath) {
+    if (outPath === INDEX_FILE) {
+        return '/';
+    }
+    return '/' + (outPath.endsWith(INDEX_SUFFIX) ? outPath.slice(0, -INDEX_SUFFIX.length) : outPath);
+}
+function toFileOutput(output) {
+    const renamed = {};
+    const errors = [];
+    const routeByFilePath = new Map();
+    for (const [outPath, file] of Object.entries(output)) {
+        const route = routeOf(outPath);
+        const filePath = toFilePath(outPath);
+        if (outPath.endsWith('/index' + INDEX_SUFFIX) || outPath === 'index' + INDEX_SUFFIX) {
+            errors.push(`Route '${route}' cannot be prerendered with 'prerenderFormat: "file"': ` +
+                `its file '${filePath}' would be served as '${route.slice(0, -'index'.length)}', not as '${route}'. ` +
+                `Rename the route or use 'prerenderFormat: "directory"'.`);
+            continue;
+        }
+        const existingRoute = routeByFilePath.get(filePath);
+        if (existingRoute !== undefined) {
+            errors.push(`Routes '${existingRoute}' and '${route}' both map to the file '${filePath}' with 'prerenderFormat: "file"'.`);
+            continue;
+        }
+        routeByFilePath.set(filePath, route);
+        renamed[filePath] = file;
+    }
+    return { output: renamed, errors };
+}
+function wrapPrerenderPages(prerenderPages) {
+    const wrapped = async function (...args) {
+        const result = await prerenderPages.apply(this, args);
+        if (!result ||
+            typeof result.output !== 'object' ||
+            result.output === null ||
+            !Array.isArray(result.errors)) {
+            throw new Error('@angular-schule/prerender-format: prerenderPages() returned an unknown result. ' +
+                'This version of @angular/build is not supported.');
+        }
+        prerenderCalls++;
+        const { output, errors } = toFileOutput(result.output);
+        return { ...result, output, errors: [...result.errors, ...errors] };
+    };
+    Object.defineProperty(wrapped, PATCHED, { value: true });
+    return wrapped;
+}
+function isPatched(fn) {
+    return fn[PATCHED] === true;
+}
+function installFileFormat(angularBuildRoot) {
+    const modulePath = path.join(angularBuildRoot, PRERENDER_MODULE);
+    let prerenderModule;
+    try {
+        prerenderModule = require(modulePath);
+    }
+    catch (error) {
+        throw new Error(`@angular-schule/prerender-format: cannot load '${modulePath}'. This version of @angular/build is not supported.`, { cause: error });
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(prerenderModule, 'prerenderPages');
+    const prerenderPages = prerenderModule.prerenderPages;
+    if (typeof prerenderPages !== 'function' || !descriptor?.writable) {
+        throw new Error(`@angular-schule/prerender-format: '${modulePath}' exports no replaceable prerenderPages(). ` +
+            'This version of @angular/build is not supported.');
+    }
+    if (!isPatched(prerenderPages)) {
+        prerenderModule.prerenderPages = wrapPrerenderPages(prerenderPages);
+    }
+}
+//# sourceMappingURL=file-format.js.map

package/application/file-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-format.js","sourceRoot":"","sources":["../../application/file-format.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\n\n/** A prerendered page as returned by `prerenderPages()` of `@angular/build`. */\nexport interface PrerenderedFile {\n  content: string;\n  appShellRoute: boolean;\n}\n\nexport type PrerenderOutput = Record<string, PrerenderedFile>;\n\nexport interface PrerenderResult {\n  output: PrerenderOutput;\n  errors?: string[];\n  [key: string]: unknown;\n}\n\nexport type PrerenderPages = (...args: unknown[]) => Promise<PrerenderResult>;\n\nexport interface FileOutputResult {\n  output: PrerenderOutput;\n  errors: string[];\n}\n\nconst INDEX_FILE = 'index.html';\nconst INDEX_SUFFIX = '/' + INDEX_FILE;\nconst PATCHED = Symbol.for('@angular-schule/prerender-format:patched');\nconst PRERENDER_MODULE = 'src/utils/server-rendering/prerender.js';\n\nlet prerenderCalls = 0;\n\n/** Number of `prerenderPages()` calls that went through the wrapper in this process. */\nexport function getPrerenderCalls(): number {\n  return prerenderCalls;\n}\n\n/**\n * Maps a prerender output path from `foo/index.html` to `foo.html`.\n * The root `index.html` of a build (start page, or locale start page with its base href) stays as is.\n */\nexport function toFilePath(outPath: string): string {\n  if (!outPath.endsWith(INDEX_SUFFIX)) {\n    return outPath;\n  }\n\n  return outPath.slice(0, -INDEX_SUFFIX.length) + '.html';\n}\n\n/** Route of an output path, for error messages: `blog/index/index.html` → `/blog/index`. */\nfunction routeOf(outPath: string): string {\n  if (outPath === INDEX_FILE) {\n    return '/';\n  }\n\n  return '/' + (outPath.endsWith(INDEX_SUFFIX) ? outPath.slice(0, -INDEX_SUFFIX.length) : outPath);\n}\n\n/**\n * Renames all keys of a prerender `output` record.\n * Routes whose last segment is `index` are reported as errors: as `…/index.html` they would be\n * served under the parent path, and `/index` would overwrite the start page.\n */\nexport function toFileOutput(output: PrerenderOutput): FileOutputResult {\n  const renamed: PrerenderOutput = {};\n  const errors: string[] = [];\n  const routeByFilePath = new Map<string, string>();\n\n  for (const [outPath, file] of Object.entries(output)) {\n    const route = routeOf(outPath);\n    const filePath = toFilePath(outPath);\n\n    if (outPath.endsWith('/index' + INDEX_SUFFIX) || outPath === 'index' + INDEX_SUFFIX) {\n      errors.push(\n        `Route '${route}' cannot be prerendered with 'prerenderFormat: \"file\"': ` +\n          `its file '${filePath}' would be served as '${route.slice(0, -'index'.length)}', not as '${route}'. ` +\n          `Rename the route or use 'prerenderFormat: \"directory\"'.`\n      );\n      continue;\n    }\n\n    const existingRoute = routeByFilePath.get(filePath);\n    if (existingRoute !== undefined) {\n      errors.push(\n        `Routes '${existingRoute}' and '${route}' both map to the file '${filePath}' with 'prerenderFormat: \"file\"'.`\n      );\n      continue;\n    }\n\n    routeByFilePath.set(filePath, route);\n    renamed[filePath] = file;\n  }\n\n  return { output: renamed, errors };\n}\n\n/**\n * Wraps `prerenderPages` so that its `output` record uses the \"file\" format.\n * Problems are returned as build errors of `prerenderPages`, so Angular reports them like any other build error.\n */\nexport function wrapPrerenderPages(prerenderPages: PrerenderPages): PrerenderPages {\n  const wrapped = async function (this: unknown, ...args: unknown[]) {\n    const result = await prerenderPages.apply(this, args);\n    if (\n      !result ||\n      typeof result.output !== 'object' ||\n      result.output === null ||\n      !Array.isArray(result.errors)\n    ) {\n      throw new Error(\n        '@angular-schule/prerender-format: prerenderPages() returned an unknown result. ' +\n          'This version of @angular/build is not supported.'\n      );\n    }\n    prerenderCalls++;\n\n    const { output, errors } = toFileOutput(result.output);\n\n    return { ...result, output, errors: [...result.errors, ...errors] };\n  };\n  Object.defineProperty(wrapped, PATCHED, { value: true });\n\n  return wrapped;\n}\n\nfunction isPatched(fn: PrerenderPages): boolean {\n  return (fn as unknown as Record<symbol, unknown>)[PATCHED] === true;\n}\n\n/**\n * Replaces `prerenderPages` of the given `@angular/build` installation.\n * `execute-post-bundle.js` reads the function from the module's exports object on every call,\n * so the replacement takes effect for regular and localized builds alike.\n */\nexport function installFileFormat(angularBuildRoot: string): void {\n  const modulePath = path.join(angularBuildRoot, PRERENDER_MODULE);\n  let prerenderModule: { prerenderPages?: PrerenderPages };\n  try {\n    prerenderModule = require(modulePath);\n  } catch (error) {\n    throw new Error(\n      `@angular-schule/prerender-format: cannot load '${modulePath}'. This version of @angular/build is not supported.`,\n      { cause: error }\n    );\n  }\n\n  const descriptor = Object.getOwnPropertyDescriptor(prerenderModule, 'prerenderPages');\n  const prerenderPages = prerenderModule.prerenderPages;\n  if (typeof prerenderPages !== 'function' || !descriptor?.writable) {\n    throw new Error(\n      `@angular-schule/prerender-format: '${modulePath}' exports no replaceable prerenderPages(). ` +\n        'This version of @angular/build is not supported.'\n    );\n  }\n\n  if (!isPatched(prerenderPages)) {\n    prerenderModule.prerenderPages = wrapPrerenderPages(prerenderPages);\n  }\n}\n"]}