benpsnyder · Sep 6, 2026 · Sep 7, 2026 · Sep 7, 2026 · Sep 7, 2026 · Sep 7, 2026
@@ -37,14 +37,22 @@ on:
   workflow_dispatch:
   pull_request:
     paths:
-      - 'packages/vite-plugin-angular/src/lib/compiler/**'
+      - 'packages/vite-plugin-angular/**'
+      - 'tools/build/**'
       - 'package.json'
+      - 'pnpm-workspace.yaml'
+      - 'pnpm-lock.yaml'
+      - '.node-version'
       - '.github/workflows/compiler-compat.yml'
   push:
     branches: [beta]
     paths:
-      - 'packages/vite-plugin-angular/src/lib/compiler/**'
+      - 'packages/vite-plugin-angular/**'
+      - 'tools/build/**'
       - 'package.json'
+      - 'pnpm-workspace.yaml'
+      - 'pnpm-lock.yaml'
+      - '.node-version'
       - '.github/workflows/compiler-compat.yml'
 
 env:
@@ -70,7 +78,7 @@ jobs:
         # signal-input array shape and aren't worth supporting). v19/v20
         # use the floor of the major as a deterministic CI signal.
         angular-version:
-          ['17.3.12', '18.2.14', '19.0.0', '20.0.0', '21.0.0', 'next']
+          ['17.3.12', '18.2.14', '19.0.0', '20.0.0', '21.0.0', '22.0.0', 'next']
 
     name: Angular ${{ matrix.angular-version }}
 
@@ -96,6 +104,10 @@ jobs:
         run: |
           node -e "
           const fs = require('fs');
+          // Alternate compiler versions qualify compiler APIs, not the entire workspace.
+          const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
+          delete pkg.scripts.prepare;
+          fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
           const f = 'pnpm-workspace.yaml';
           const v = '${{ matrix.angular-version }}';
           const pinned = ['@angular/compiler', '@angular/compiler-cli'];
@@ -217,3 +229,59 @@ jobs:
               --label "bug,vite-plugin-angular" \
               --body "$BODY"
           fi
+
+  consumer-compat:
+    name: Angular ${{ matrix.angular }} / Vite ${{ matrix.vite }} consumer
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { angular: '17.3.12', vite: '6.0.0', node: '20.19.5' }
+          - { angular: '18.2.14', vite: '6.0.0', node: '20.19.5' }
+          - { angular: '19.0.0', vite: '6.0.0', node: '20.19.5' }
+          - { angular: '20.0.0', vite: '6.0.0' }
+          - { angular: '20.1.0', vite: '6.0.0' }
+          - { angular: '21.0.0', vite: '7.0.0' }
+          - { angular: '22.0.0', vite: '6.0.0' }
+          - { angular: '22.0.0', vite: '7.0.0' }
+          - { angular: '22.0.0', vite: '8.0.8' }
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install supported Node for legacy Angular consumers
+        if: matrix.node != ''
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Record the consumer Node executable
+        if: matrix.node != ''
+        id: consumer-node
+        run: echo "path=$(node -p 'process.execPath')" >> "$GITHUB_OUTPUT"
+      - uses: actions/setup-node@v3
+        with:
+          node-version-file: .node-version
+      - run: npm install --global corepack@0.31.0
+      - run: corepack enable
+      - name: Install workspace without unrelated package prepare builds
+        run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Test the installed package in an isolated Angular/Vite consumer
+        env:
+          ANALOG_CONSUMER_NODE: ${{ steps.consumer-node.outputs.path }}
+          NX_DAEMON: 'false'
+          NX_NO_CLOUD: 'true'
+        run: pnpm exec nx run vite-plugin-angular:compat-smoke --vite=${{ matrix.vite }} --angular=${{ matrix.angular }}
+      - name: Check compiler package tests, declarations, and lint
+        if: matrix.angular == '22.0.0' && matrix.vite == '8.0.8'
+        env:
+          NX_DAEMON: 'false'
+          NX_NO_CLOUD: 'true'
+        run: pnpm exec nx run-many --targets=test,typecheck,eslint:lint --projects=vite-plugin-angular --parallel=1
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: compiler-angular-${{ matrix.angular }}-vite-${{ matrix.vite }}
+          path: |
+            dist/compiler-vite-smoke/**/result.json
+            dist/compiler-vite-smoke/**/*-failure.json
+            dist/compiler-vite-smoke/*/pnpm-lock.yaml
+          if-no-files-found: warn
@@ -4,14 +4,20 @@ on:
   workflow_dispatch:
   pull_request:
     paths:
-      - 'packages/vite-plugin-angular/src/lib/compiler/**'
+      - 'packages/vite-plugin-angular/**'
       - 'package.json'
+      - 'pnpm-workspace.yaml'
+      - 'pnpm-lock.yaml'
+      - '.node-version'
       - '.github/workflows/conformance.yml'
   push:
     branches: [beta]
     paths:
-      - 'packages/vite-plugin-angular/src/lib/compiler/**'
+      - 'packages/vite-plugin-angular/**'
       - 'package.json'
+      - 'pnpm-workspace.yaml'
+      - 'pnpm-lock.yaml'
+      - '.node-version'
       - '.github/workflows/conformance.yml'
 
 env:

@@ -1 +1 @@
-24.14.1
+24.15.0
@@ -0,0 +1 @@
+.node-version
@@ -23,10 +23,8 @@ launch-templates:
         uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
 
       - name: Install Node
-        # Reads `.node-version` (24.11.0). The base image ships Node 24.14, so we
-        # install the pinned version to preserve the old `node-version-file`
-        # behavior. Verify this reusable step picks up `.node-version`; if not,
-        # pass the version explicitly via its inputs.
+        # This step reads .nvmrc, which points to the shared .node-version pin.
+        # Install Node 24.15.0 instead of falling back to the Node 24.14 image.
         uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node/main.yaml'
 
       - name: Enable Corepack and pnpm
@@ -53,10 +51,6 @@ launch-templates:
           pnpm install --frozen-lockfile --prefer-offline
 
       - name: Install browsers
-        # Agents run both `test` (Vitest + Chromium shell) and `e2e` (Playwright
-        # + Cypress) tasks, so the full browser superset is installed once. This
-        # is heavier than either old job alone but is required because any agent
-        # may receive either task family.
+        # Vitest browser tests and Playwright E2E targets share these binaries.
         script: |
           pnpm playwright install --with-deps
-          pnpm cypress install
@@ -15,6 +15,9 @@ Source code for the Analog framework exists under the `packages/` folder. To con
 
 Analog uses [pnpm](https://pnpm.io/) to manage its dependencies.
 
+Use the Node.js version pinned in `.node-version`. The `.nvmrc` symlink shares
+that pin with nvm and the Nx Agents installer.
+
 Before opening a pull request, run the following command from the root folder to make sure your development dependencies are up-to-date:
 
 ```shell

@@ -0,0 +1,25 @@
+import { expect, test } from '@playwright/test';
+
+test('caller hints cannot disable SSR on an enabled route', async ({
+  request,
+}) => {
+  for (const supplied of [false, true]) {
+    const response = await request.get('/products/1?ssr-policy=1', {
+      headers: supplied ? { 'x-analog-no-ssr': 'true' } : {},
+    });
+    expect(response.status()).toBe(200);
+    const html = await response.text();
+    expect(html).toContain('Product Details');
+    expect(html).toContain('ng-server-context');
+  }
+});
+
+test('caller hints cannot enable SSR on a configured client route', async ({
+  request,
+}) => {
+  const response = await request.get('/cart', {
+    headers: { 'x-analog-no-ssr': 'false' },
+  });
+  expect(response.status()).toBe(200);
+  expect(await response.text()).not.toContain('ng-server-context');
+});
@@ -94,6 +94,7 @@ export default defineConfig(async ({ mode, command }) => {
       }),
       nitro({
         routeRules: {
+          '/products/**': { ssr: true },
           '/client': { ssr: false },
           '/cart/**': { ssr: false },
           '/404.html': { ssr: false },

@@ -28,23 +28,35 @@ For more information about externals with SSR, check out the [Vite documentation
 
 SSR is enabled by default. For a hybrid approach, you can specify some routes to only be rendered client-side, and not be server side rendered. This is done through the `routeRules` configuration object by specifying an `ssr` option.
 
+In Analog v3, configure these rules on the separate Nitro plugin. A more specific
+`ssr: true` rule enables server rendering under a parent rule that disables it.
+
 ```ts
 // https://vitejs.dev/config/
+import { defineConfig } from 'vite';
+import analog from '@analogjs/platform';
+import angular from '@analogjs/vite-plugin-angular';
+import { nitro } from 'nitro/vite';
+
 export default defineConfig(({ mode }) => ({
   // ...other config
   plugins: [
     analog({
       prerender: {
         routes: ['/', '/404.html'],
       },
-      nitro: {
-        routeRules: {
-          // All admin URLs are only rendered on the client
-          '/admin/**': { ssr: false },
+    }),
+    angular(),
+    nitro({
+      routeRules: {
+        // All admin URLs are only rendered on the client
+        '/admin/**': { ssr: false },
 
-          // Render a 404 page as a fallback page
-          '/404.html': { ssr: false },
-        },
+        // A specific child can opt back into server rendering
+        '/admin/help': { ssr: true },
+
+        // Render a 404 page as a fallback page
+        '/404.html': { ssr: false },
       },
     }),
   ],

@@ -1,9 +1,10 @@
 # Angular Compilation
 
-The AnalogJS Vite Plugin (`@analogjs/vite-plugin-angular`) compiles your Angular components, directives, and pipes to Ivy definitions during the Vite build. It provides two compilation paths:
+The AnalogJS Vite Plugin (`@analogjs/vite-plugin-angular`) compiles your Angular components, directives, and pipes to Ivy definitions during the Vite build. It provides these compilation paths:
 
-- **Default compilation**: Angular's own compiler (`ngtsc`), with full compile-time type checking.
+- **Default compilation**: Angular's own compiler (`NgtscProgram`), with optional compile-time type checking.
 - **Fast compile**: an in-tree single-pass compiler that produces the same Ivy output much faster.
+- **Experimental Compilation API**: Angular's build compilation API, enabled explicitly with a compatible `@angular/build` installation.
 
 Both emit identical Ivy code and identical runtime behavior, because both ultimately call the same `@angular/compiler` lowering APIs.
 
@@ -25,7 +26,31 @@ export default defineConfig({
 });
 ```
 
-The default path runs Angular's compiler through the Angular Compilation API. It performs **full TypeScript and template type checking** (including `strictTemplates`), emits declaration files, and supports i18n message extraction. Use it when you want compile-time safety: wrong template bindings, missing inputs, and type mismatches fail the build.
+The default path uses `NgtscProgram`; `experimental.useAngularCompilationAPI` defaults to `false`. Set `disableTypeChecking: false` and enable `strictTemplates` in your Angular compiler options when TypeScript and template errors must fail the build. Type checking is disabled by default for build throughput.
+
+```ts
+angular({ disableTypeChecking: false });
+```
+
+## Experimental Compilation API
+
+With an `@angular/build` version that exposes `createAngularCompilation` through `@angular/build/private`, opt into Angular's build compilation API:
+
+```ts
+angular({
+  experimental: { useAngularCompilationAPI: true },
+  disableTypeChecking: false,
+  include: ['src/integrations/**/*.ts'],
+});
+```
+
+Configured TypeScript roots, integration-provided includes, and expanded project roots are combined before compilation. The normal compiler also includes file-replacement targets, so replacement components outside the original tsconfig are AOT-compiled instead of falling through to a generic TypeScript transform.
+
+The Angular version alone does not establish availability: for example, `@angular/build@20.1.0` does not expose this factory. Unsupported installations fail during configuration with an actionable diagnostic. Leave the option disabled to use normal compilation on those versions.
+
+For Vite library builds, the experimental API emits JavaScript only. Generate `.d.ts` files in a separate declaration step. Angular's compilation API returns one result per source file, so enabling declaration emit there would overwrite the JavaScript result with declaration text. The repository's package builds use their own declaration-emission step.
+
+Both paths wait for active compilation before transforming emitted modules. Experimental compilation shares its emitted modules with the HMR middleware; template-only changes invalidate the affected component and deliver Angular's replacement metadata. Compiler shutdown waits for active work before disposing its worker. Plugin setup and stylesheet errors preserve the original exception as `cause` together with the plugin/file context.
 
 ## Fast compile
 
@@ -50,13 +75,15 @@ export default defineConfig({
 ```
 
 :::note
-In an Analog application, configure the plugin through `@analogjs/platform` instead. Its `analog()` plugin forwards the same `fastCompile` option:
+In an Analog v3 application, configure compilation on `angular()` alongside the platform plugin:
 
 ```ts
 import analog from '@analogjs/platform';
+import angular from '@analogjs/vite-plugin-angular';
+import { nitro } from 'nitro/vite';
 
 export default defineConfig({
-  plugins: [analog({ fastCompile: true })],
+  plugins: [analog(), angular({ fastCompile: true }), nitro()],
 });
 ```
 
@@ -157,15 +184,27 @@ Fast compile is validated against Angular `17`, `18`, `19`, `20`, `21`, `22`, an
 
 For overall Angular/Analog/Vite version support, see [Version Compatibility](/docs/guides/compatibility).
 
+### Compiler contributor checks
+
+The compiler compatibility workflow separates compiler API tests from installed-package consumer builds. The consumer matrix uses Angular 17.3, 18.2, 19.0, 20.0, and 20.1 with Vite 6; Angular 21 with Vite 7; and Angular 22 with Vite 6, 7, and 8. It is a representative matrix, not every possible cross-product. The experimental path is checked when the installed build package exposes it; other tuples verify the explicit rejection as well as normal and fast compilation.
+
+Run one tuple from the repository root:
+
+```bash
+pnpm exec nx run vite-plugin-angular:compat-smoke --vite=8.0.8 --angular=22.0.0
+```
+
+The target builds and packs the package, installs it into an isolated consumer, and checks normal compilation, additional roots/replacements, and fast full/partial compilation. It also checks experimental Compilation API output on supported Angular versions. Angular 22 tuples additionally use Chromium to verify template HMR preserves component state in both compiler modes, and that boot/manual reload works with Angular HMR disabled. Each run retains its exact installed versions, lockfile, and result under `dist/compiler-vite-smoke/`.
+
 ### Default vs fast compile
 
-|                                     | Default                 | Fast compile                          |
-| ----------------------------------- | ----------------------- | ------------------------------------- |
-| Ivy output                          | Full                    | Identical                             |
-| Cold build / hot rebuild            | Standard                | Significantly faster                  |
-| Compile-time template type checking | Yes (`strictTemplates`) | No (use the Angular Language Service) |
-| i18n message extraction             | Yes                     | `$localize` emitted                   |
-| Library / partial builds            | Yes                     | Yes (`fastCompileMode: 'partial'`)    |
+|                                     | Default                                                        | Fast compile                          |
+| ----------------------------------- | -------------------------------------------------------------- | ------------------------------------- |
+| Ivy output                          | Full                                                           | Identical                             |
+| Cold build / hot rebuild            | Standard                                                       | Significantly faster                  |
+| Compile-time template type checking | Opt in with `disableTypeChecking: false` and `strictTemplates` | No (use the Angular Language Service) |
+| i18n message extraction             | Yes                                                            | `$localize` emitted                   |
+| Library / partial builds            | Yes                                                            | Yes (`fastCompileMode: 'partial'`)    |
 
 ## Trade-offs
 

@@ -242,6 +242,10 @@ describe('analogNitroPlugin', () => {
         routeRules: {
           '/buffered': { streaming: false },
           '/no-ssr': { ssr: false },
+          '/no-ssr/help': {
+            ssr: true,
+            headers: { 'x-analog-no-ssr': 'true', 'x-example': 'retained' },
+          },
           '/default': {},
         },
       },
@@ -255,6 +259,10 @@ describe('analogNitroPlugin', () => {
     expect(nitroMock.options.routeRules['/no-ssr'].headers).toEqual({
       'x-analog-no-ssr': 'true',
     });
+    expect(nitroMock.options.routeRules['/no-ssr/help'].headers).toEqual({
+      'x-analog-no-ssr': 'false',
+      'x-example': 'retained',
+    });
     expect(nitroMock.options.routeRules['/default'].headers).toBeUndefined();
   });
 });