feat!: prerender.format as a separate object, as in angular/angular-cli#34180 (0.4.0)

As in the pull request after its review, `format` is a separate object
in the `oneOf` of the prerender option, so it cannot be combined with
routesFile and discoverRoutes, which only apply without outputMode.
`format` is required in that object, so `"prerender": {}` keeps
matching the object of @angular/build only. Schema defaults no longer
add `format` to that object, so with outputMode the builder warns for
every prerender value other than an object with `format`. A schema
test covers both objects.

BREAKING CHANGE: `prerender.format` cannot be combined with
`routesFile` or `discoverRoutes`. `ng add` stops if the prerender
option contains them.

Author: JohannesHoppe

CLAUDE.md

@@ -26,7 +26,7 @@ Build process: `prebuild` (clean) → `build` (tsc) → `postbuild` (copy metada
 ```bash
 npm run build:schema
 ```
-`application/schema.json` is generated: the schema of `@angular/build:application` from the installed version plus `format` in the `prerender` object. Regenerate it after updating `@angular/build` and commit the result. `npm test` fails if it is out of sync.
+`application/schema.json` is generated: the schema of `@angular/build:application` from the installed version plus a separate object with `format` in the `oneOf` of `prerender`, as in the pull request, so `format` cannot be combined with `routesFile` and `discoverRoutes`. `format` is required in that object, so `{}` keeps matching the object of `@angular/build` only. Regenerate it after updating `@angular/build` and commit the result. `npm test` fails if it is out of sync.
 
 ### Test
 ```bash
@@ -77,14 +77,14 @@ The option must never make a build fail. Whenever the "file" format does not app
 ## Architecture
 
 1. **Builder** (`src/application/`):
-   - `builder.ts` - Angular builder entry point, called by `ng build`. Takes `format` out of the `prerender` option (`toApplicationOptions()`) and delegates to `buildApplication`. With `outputMode`, `@angular/build` ignores `prerender`, so the builder drops it there and applies only `format`. If one of the other `prerender` settings has no effect, the builder warns with the rule and the message of the pull request. Whenever the "file" format does not apply (a server is produced, the internals of `@angular/build` differ, nothing went through the wrapper), it logs a warning and the build behaves like `@angular/build:application`.
+   - `builder.ts` - Angular builder entry point, called by `ng build`. Takes `format` out of the `prerender` option (`toApplicationOptions()`) and delegates to `buildApplication`. With `outputMode`, `@angular/build` ignores `prerender`, so the builder drops it there and applies only `format`. If `prerender` is set to anything other than an object with `format`, the builder warns with the rule and the message of the pull request. Whenever the "file" format does not apply (a server is produced, the internals of `@angular/build` differ, nothing went through the wrapper), it logs a warning and the build behaves like `@angular/build:application`.
    - `ships-server.ts` - The rule for "this build ships an SSR server", shared by builder and `ng add`.
    - `file-format.ts` - Wraps the internal `prerenderPages()` of `@angular/build`. `execute-post-bundle.js` reads it from the module's exports object at call time, so replacing the export takes effect for regular and localized builds.
    - `schema.json` - Generated, see above.
 
 2. **Schematic** (`src/ng-add.ts`):
    - Implements `ng add @angular-schule/prerender-format`
-   - Swaps the build target's builder and sets `prerender.format: "file"`, keeping other `prerender` settings
+   - Swaps the build target's builder and sets `"prerender": { "format": "file" }`; stops if `prerender` contains `routesFile` or `discoverRoutes`, which cannot be combined with `format`
    - Warns if the build target or one of its configurations produces an SSR server
 
 ### Internal API

README.md

@@ -64,6 +64,7 @@ ng build
 
 `ng add @angular-schule/prerender-format` installs the package, changes the builder of your build target in `angular.json` and sets `prerender.format`.
 `"format": "file"` only applies to static builds. If the build target (or one of its configurations) produces an SSR server, `ng add` still sets it up and shows a warning.
+If `prerender` contains `routesFile` or `discoverRoutes`, `ng add` stops, as they cannot be combined with `format`.
 
 ```json
 "build": {
@@ -97,7 +98,8 @@ 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`.
 
-`prerender.format` is also considered with `"outputMode": "static"`, where Angular ignores the other `prerender` settings.
+`prerender.format` cannot be combined with `routesFile` and `discoverRoutes`, which only apply to builds without `"outputMode"`.
+With `"outputMode": "static"`, Angular ignores every other value of `prerender`, and `prerender.format` is considered.
 
 ## 🔭 Other frameworks <a name="other-frameworks"></a>
 

src/application/builder.spec.ts

@@ -9,20 +9,28 @@ describe('toApplicationOptions', () => {
     });
   });
 
-  it('removes the format from the prerender options of a build without outputMode', () => {
-    expect(toApplicationOptions({ prerender: { format: 'file', discoverRoutes: true } } as never)).toEqual({
-      applicationOptions: { prerender: { discoverRoutes: true } },
+  it('removes the format from the prerender option of a build without outputMode', () => {
+    expect(toApplicationOptions({ prerender: { format: 'file' } } as never)).toEqual({
+      applicationOptions: { prerender: {} },
       format: 'file',
       prerenderIgnored: false
     });
   });
 
+  it('passes the prerender settings of @angular/build through without outputMode', () => {
+    expect(toApplicationOptions({ prerender: { routesFile: 'routes.txt', discoverRoutes: true } } as never)).toEqual({
+      applicationOptions: { prerender: { routesFile: 'routes.txt', discoverRoutes: true } },
+      format: 'directory',
+      prerenderIgnored: false
+    });
+  });
+
   it('drops the prerender option with outputMode and keeps the format', () => {
     expect(
       toApplicationOptions({
         outputMode: 'static',
         server: 'src/main.server.ts',
-        prerender: { format: 'file', discoverRoutes: true }
+        prerender: { format: 'file' }
       } as never)
     ).toEqual({
       applicationOptions: { outputMode: 'static', server: 'src/main.server.ts' },
@@ -32,14 +40,15 @@ describe('toApplicationOptions', () => {
   });
 
   it.each([
-    ['routesFile', { format: 'file', routesFile: 'routes.txt', discoverRoutes: true }],
-    ['discoverRoutes: false', { format: 'file', discoverRoutes: false }],
+    ['routesFile', { routesFile: 'routes.txt', discoverRoutes: true }],
+    ['discoverRoutes: false', { discoverRoutes: false }],
+    ['discoverRoutes: true', { discoverRoutes: true }],
     ['true', true],
     ['false', false]
   ])('reports prerender with %s as ignored with outputMode', (_, prerender) => {
     expect(toApplicationOptions({ outputMode: 'static', server: 'src/main.server.ts', prerender } as never)).toEqual({
       applicationOptions: { outputMode: 'static', server: 'src/main.server.ts' },
-      format: typeof prerender === 'object' ? 'file' : 'directory',
+      format: 'directory',
       prerenderIgnored: true
     });
   });

src/application/builder.ts

@@ -11,7 +11,8 @@ type PrerenderObject = Exclude<ApplicationBuilderOptions['prerender'], boolean |
 
 export interface Schema extends Omit<ApplicationBuilderOptions, 'prerender'> {
   /**
-   * Same as the `prerender` option of `@angular/build:application`, plus `format`:
+   * Same as the `prerender` option of `@angular/build:application`, or an object with `format`
+   * (`schema.json` does not allow `format` together with `routesFile` or `discoverRoutes`):
    * - `directory` (default): `/foo` is written to `foo/index.html`
    * - `file`: `/foo` is written to `foo.html`, the start page stays `index.html`
    */
@@ -21,8 +22,8 @@ export interface Schema extends Omit<ApplicationBuilderOptions, 'prerender'> {
 /**
  * Splits `prerender.format` from the options that `@angular/build:application` understands.
  * With `outputMode`, `@angular/build` does not consider the `prerender` option, only `format` applies.
- * The `prerender` option is dropped there, and `prerenderIgnored` tells whether one of its other
- * settings has no effect, with the rule of angular/angular-cli#34180.
+ * The `prerender` option is dropped there, and `prerenderIgnored` tells whether it is set to anything
+ * other than an object with `format`, with the rule of angular/angular-cli#34180.
  */
 export function toApplicationOptions(options: Schema): {
   applicationOptions: ApplicationBuilderOptions;
@@ -40,12 +41,8 @@ export function toApplicationOptions(options: Schema): {
     };
   }
 
-  // Values are compared, as schema defaults are added to the "prerender" object.
   const prerenderIgnored =
-    prerender !== undefined &&
-    (typeof prerender !== 'object' ||
-      prerenderOptions.routesFile !== undefined ||
-      prerenderOptions.discoverRoutes === false);
+    prerender !== undefined && (typeof prerender === 'boolean' || !('format' in prerender));
 
   return { applicationOptions: rest, format, prerenderIgnored };
 }

src/application/schema.json

@@ -620,18 +620,26 @@
               "type": "boolean",
               "description": "Whether the builder should process the Angular Router configuration to find all unparameterized routes and prerender them.",
               "default": true
-            },
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
             "format": {
               "type": "string",
               "description": "Defines the file layout of prerendered 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'. Only considered when the build does not produce a server.",
               "enum": [
                 "directory",
                 "file"
-              ],
-              "default": "directory"
+              ]
             }
           },
-          "additionalProperties": false
+          "additionalProperties": false,
+          "required": [
+            "format"
+          ]
         }
       ]
     },

src/application/schema.spec.ts

@@ -0,0 +1,38 @@
+import { schema } from '@angular-devkit/core';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const applicationSchema = JSON.parse(fs.readFileSync(path.join(__dirname, 'schema.json'), 'utf8'));
+
+/** Validates `prerender` as `ng build` does for this builder, including the schema defaults. */
+async function validatePrerender(prerender: unknown): Promise<{ success: boolean; prerender: unknown }> {
+  const registry = new schema.CoreSchemaRegistry();
+  registry.addPostTransform(schema.transforms.addUndefinedDefaults);
+  const validator = await registry.compile(applicationSchema);
+  const { success, data } = await validator({ tsConfig: 'tsconfig.app.json', prerender } as never);
+
+  return { success, prerender: (data as { prerender: unknown }).prerender };
+}
+
+describe('application/schema.json', () => {
+  it('accepts an object with format', async () => {
+    expect(await validatePrerender({ format: 'file' })).toEqual({ success: true, prerender: { format: 'file' } });
+  });
+
+  it.each([{}, { routesFile: 'routes.txt' }, { discoverRoutes: false }])(
+    'keeps %o an object of @angular/build, without format',
+    async prerender => {
+      const result = await validatePrerender(prerender);
+
+      expect(result.success).toBe(true);
+      expect(Object.keys(result.prerender as object)).not.toContain('format');
+    }
+  );
+
+  it.each([
+    { format: 'file', routesFile: 'routes.txt' },
+    { format: 'file', discoverRoutes: false }
+  ])('rejects format together with the settings of @angular/build: %o', async prerender => {
+    expect((await validatePrerender(prerender)).success).toBe(false);
+  });
+});

src/ng-add.spec.ts

@@ -69,13 +69,17 @@ describe('ng-add', () => {
     });
   });
 
-  it('adds the format to existing prerender settings', async () => {
+  it('refuses prerender settings that cannot be combined with the format', async () => {
     const tree = Tree.empty();
-    tree.create('angular.json', angularJson({ site: app(undefined, { prerender: { routesFile: 'routes.txt' } }) }));
-
-    await ngAdd({ project: 'site' })(tree, mockContext);
+    tree.create(
+      'angular.json',
+      angularJson({ site: app(undefined, { prerender: { routesFile: 'routes.txt', discoverRoutes: false } }) })
+    );
 
-    expect(buildTarget(tree, 'site').options).toEqual({ prerender: { routesFile: 'routes.txt', format: 'file' } });
+    await expect(ngAdd({ project: 'site' })(tree, mockContext)).rejects.toThrow(
+      '"prerender.format" cannot be combined with "routesFile" and "discoverRoutes".'
+    );
+    expect(buildTarget(tree, 'site').builder).toBe('@angular/build:application');
   });
 
   it('switches a build that produces a server, with a warning', async () => {

src/ng-add.ts

@@ -66,11 +66,17 @@ export const ngAdd = (options: NgAddOptions) => async (tree: Tree, context: Sche
     .map(([name]) => name);
 
   const prerender = buildTarget.options?.prerender;
+  const prerenderSettings = isJsonObject(prerender) ? Object.keys(prerender).filter(key => key !== 'format') : [];
+  if (prerenderSettings.length > 0) {
+    const settings = prerenderSettings.map(key => `"${key}"`).join(' and ');
+    throw new SchematicsException(
+      `"prerender.format" cannot be combined with ${settings}. ` +
+        `Remove ${settings} from the "prerender" option of "${options.project}" and run ng add again.`
+    );
+  }
+
   buildTarget.builder = BUILDER_NAME;
-  buildTarget.options = {
-    ...buildTarget.options,
-    prerender: { ...(isJsonObject(prerender) ? prerender : {}), format: 'file' }
-  };
+  buildTarget.options = { ...buildTarget.options, prerender: { format: 'file' } };
 
   await workspaces.writeWorkspace(workspace, host);
 

src/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-schule/prerender-format",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Angular application builder that writes prerendered routes as foo.html instead of foo/index.html (no trailing slash redirects)",
   "main": "index.js",
   "types": "index.d.ts",