feat(platform)!: migrate to nitro/vite and split analog() into analog() + angular() + nitro()

[brandonroberts]

PR Checklist

Migrates Analog to Nitro v3's first-party Vite plugin (nitro/vite) and reshapes @analogjs/platform's plugin surface. analog() no longer composes @analogjs/vite-plugin-angular or Nitro internally — users wire analog() + angular() + nitro() as three explicit plugins.

Closes #2035

Affected scope

• Primary scope: platform
• Secondary scopes: vite-plugin-angular, vite-plugin-nitro, create-analog

Recommended merge strategy for maintainer [optional]

• Squash merge
• Rebase merge
• Other

What is the new behavior?

Plugin chain is now explicit (breaking)

analog() used to invoke @analogjs/vite-plugin-angular and @analogjs/vite-plugin-nitro internally. v3 splits the chain into three plugins users compose themselves:

import analog from '@analogjs/platform';
import angular from '@analogjs/vite-plugin-angular';
import { nitro } from 'nitro/vite';

export default defineConfig(() => ({
  plugins: [analog(), angular(), nitro()],
}));

• @analogjs/platform owns its own Nitro orchestration through nitro/vite directly (via a new analogNitroPlugin registered as a Nitro module).
• @analogjs/vite-plugin-nitro continues to ship as a standalone package (orchestration helpers were copied into platform — the two evolve independently).

Architect builder shims for the platform vite executor

• @analogjs/vite-plugin-angular publishes ./builders/vite and ./builders/vite-dev-server subpath exports.
• @analogjs/platform ships local Architect-builder shims that import + re-export from those subpaths (storybook-angular pattern). Drops the vite: "@analogjs/vite-plugin-angular:vite" string redirect from builders.json so Architect lands on a real local file on first lookup.
• Dropped the broken Nx vite executor that forwarded to @nx/vite's viteBuildExecutor (it never called buildApp()).

Output layout preserved

Nitro's final output paths are pinned in analogNitroPlugin.setup() to the legacy dist/<rootDir>/analog/{server,public,nitro.json} layout for build only. Dev mode keeps Nitro defaults so the dev server's readAsset doesn't crash on the unbuilt dist/. buildDir stays at Nitro's default so Rolldown's prerender rebundle finds workspace deps in node_modules/.

Platform owns the server.fs.allow workaround

Vite 8's strict fs would otherwise reject nitro/vite's env-runner load of its own dev-entry.mjs (a pnpm content-hash path). analogNitroPlugin.config() now contributes server.fs.allow: [workspaceRoot] so user vite.config.ts files don't carry the workaround.

ng-update schematic for plugin separation

@analogjs/platform's ng-update migration migrate-to-separated-plugins:

• Detects legacy analog({ ... }) shape via TypeScript AST traversal.
• Rewrites analog({ vite: {...}, nitro: {...}, ... }) into analog({...}), angular({...}), nitro({...}), lifting vite/nitro keys into their owning plugin while preserving remaining analog options.
• Rewrites argumentless analog() into analog(), angular(), nitro().
• Adds @analogjs/vite-plugin-angular to devDependencies (version mirrors @analogjs/platform's pin).
• Tests assert mirroring behavior, not a specific release line.

Templates updated

• create-analog's latest, blog, and minimal templates use the separated plugin shape.
• nitro is injected only for pnpm scaffolds (addPnpmDependencies) since npm/yarn auto-hoist it as a transitive of @analogjs/platform; pnpm's strict isolation needs the top-level declaration.

Other notable changes

• Demo apps (analog-app, blog-app, opt-catchall-app, tailwind-debug-app, tanstack-query-app) all on @analogjs/platform:vite builder.
• discoverLibraryRoutes + pageGlobs helpers re-exported from @analogjs/platform (single call, fed to both analog() and angular()).
• Options.useAPIMiddleware and Options.ssrBuildDir dropped — both were unused; the api-middleware fallback is being removed in v3 anyway.
• Migration guide section added: apps/docs-app/docs/guides/migrating-v2-to-v3.md.
• nitro pin bumped to 3.0.260522-beta (latest beta).
• Per-app server.fs.allow workaround removed; experimental.websocket flag gated behind process.env.VITEST in tailwind-debug-app so Vitest run doesn't crash.

Test plan

• nx format:check
• pnpm build (22/22 projects)
• pnpm test (18/18 projects)
• Manual verification:
  • pnpm nx build analog-app emits dist/apps/analog-app/analog/server/index.mjs, nitro.json, and prerendered HTML
  • node dist/apps/analog-app/analog/server/index.mjs serves SSR routes with hydration tokens, API routes with JSON, and ssr: false routes with the raw template
  • pnpm nx serve analog-app boots cleanly without user-side server.fs.allow
  • migrate-to-separated-plugins schematic: 15/15 unit tests pass

Does this PR introduce a breaking change?

• Yes
• No

Breaking changes (all documented in docs/guides/migrating-v2-to-v3.md with the schematic covering most cases):

• analog() no longer composes angular() or nitro() — users must call all three.
• @analogjs/platform v3 no longer composes @analogjs/vite-plugin-nitro internally (vpn keeps shipping standalone).
• Options.useAPIMiddleware and Options.ssrBuildDir removed.

Other information

• Branch is 42 commits, organized per-package scope. Squash-merge will compact them into one commit on alpha.

🤖 Generated with Claude Code

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

packages/platform/src/lib/nitro/analog-nitro-plugin.ts (1)

649-677: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Restore staticData endpoint prerendering for PrerenderContentDir routes.

collectRoutes() now restores outputSourceFile, but it still skips the staticData expansion in the contentDir branch. That drops /<apiPrefix>/_analog/pages/... prerenders for transformed content routes and breaks parity with prior behavior.

Proposed fix

       for (const file of files) {
         const route = dir.transform(file);
         if (route === false) continue;
         out.push(route);
@@
         if (dir.outputSourceFile) {
           const sourceContent = dir.outputSourceFile(file);
           if (typeof sourceContent === 'string') {
             routeSourceFiles[route] = sourceContent;
           }
         }
+        if (dir.staticData) {
+          const prefix = apiPrefix.startsWith('/') ? apiPrefix : `/${apiPrefix}`;
+          const normalizedRoute = route.startsWith('/') ? route : `/${route}`;
+          out.push(`${prefix}/_analog/pages${normalizedRoute}`);
+        }
       }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/platform/src/lib/nitro/analog-nitro-plugin.ts` around lines 649 -
677, In collectRoutes (analog-nitro-plugin.ts) the PrerenderContentDir branch
processes transform(), sitemaps and outputSourceFile but does not add the
corresponding staticData prerender routes (the /<apiPrefix>/_analog/pages/...
endpoints), causing missing prerenders; update the 'contentDir' branch
(PrerenderContentDir handling) to mirror the staticData expansion logic used
elsewhere: after computing route and routeSourceFiles[route], also push the
generated staticData route(s) into out (using the same route -> static data
endpoint naming as the rest of collectRoutes) and include any associated
routeSourceFiles/sitemaps entries the same way so transformed content routes get
their /_analog/pages/* prerenders restored.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/platform/src/lib/nitro/i18n-prerender.ts`:
- Around line 24-28: The route-exclusion predicate in i18n-prerender.ts
currently hardcodes '/api'; update it to honor the configured apiPrefix by
changing the predicate to check route === apiPrefix ||
route.startsWith(apiPrefix + '/') and by accepting an apiPrefix parameter into
the function (or into wirePrerender's internal call) so the correct prefix is
used; update the caller (wirePrerender) to pass the configured apiPrefix through
to this check so custom API prefixes (e.g., '/rpc') are excluded from locale
expansion.

---

Duplicate comments:
In `@packages/platform/src/lib/nitro/analog-nitro-plugin.ts`:
- Around line 649-677: In collectRoutes (analog-nitro-plugin.ts) the
PrerenderContentDir branch processes transform(), sitemaps and outputSourceFile
but does not add the corresponding staticData prerender routes (the
/<apiPrefix>/_analog/pages/... endpoints), causing missing prerenders; update
the 'contentDir' branch (PrerenderContentDir handling) to mirror the staticData
expansion logic used elsewhere: after computing route and
routeSourceFiles[route], also push the generated staticData route(s) into out
(using the same route -> static data endpoint naming as the rest of
collectRoutes) and include any associated routeSourceFiles/sitemaps entries the
same way so transformed content routes get their /_analog/pages/* prerenders
restored.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6c0ef65c-acd9-421c-a5dc-6d94f4901b81

📥 Commits

Reviewing files that changed from the base of the PR and between 94667f4 and 6db73b9.

📒 Files selected for processing (8)

• packages/nx-plugin/src/builders/vite-dev-server/schema.json
• packages/platform/src/lib/nitro/analog-nitro-plugin.ts
• packages/platform/src/lib/nitro/build-sitemap.ts
• packages/platform/src/lib/nitro/get-content-files.ts
• packages/platform/src/lib/nitro/get-page-handlers.ts
• packages/platform/src/lib/nitro/i18n-prerender.ts
• packages/platform/src/lib/nitro/post-rendering-hook.ts
• packages/platform/src/lib/nitro/renderers.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Make API-route exclusion honor configured apiPrefix, not hardcoded /api.

This predicate still hardcodes /api. For custom prefixes, API routes may be incorrectly locale-expanded (e.g., /rpc/... becoming /en/rpc/...).

Proposed direction

-export function expandRoutesWithLocales(
+export function expandRoutesWithLocales(
   routes: string[],
   i18n: I18nPrerenderOptions,
+  apiPrefix = 'api',
 ): string[] {
+  const normalizedApiPrefix = apiPrefix.startsWith('/')
+    ? apiPrefix
+    : `/${apiPrefix}`;
@@
     if (
       route.includes('/_analog/') ||
-      route === '/api' ||
-      route.startsWith('/api/')
+      route === normalizedApiPrefix ||
+      route.startsWith(`${normalizedApiPrefix}/`)
     ) {

…and pass apiPrefix from the wirePrerender() caller.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/platform/src/lib/nitro/i18n-prerender.ts` around lines 24 - 28, The
route-exclusion predicate in i18n-prerender.ts currently hardcodes '/api';
update it to honor the configured apiPrefix by changing the predicate to check
route === apiPrefix || route.startsWith(apiPrefix + '/') and by accepting an
apiPrefix parameter into the function (or into wirePrerender's internal call) so
the correct prefix is used; update the caller (wirePrerender) to pass the
configured apiPrefix through to this check so custom API prefixes (e.g., '/rpc')
are excluded from locale expansion.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/platform/src/lib/nitro/analog-nitro-plugin.ts`:
- Around line 238-240: The isVercel detection currently treats any VERCEL env
var as true even when an explicit Nitro preset is set; change the logic so an
explicit nitro.options.preset always wins: compute the preset
(nitro.options.preset) first and only consider process.env['VERCEL'] when the
preset is empty/undefined, i.e. make isVercel true if the preset contains
'vercel' OR if there is no preset and VERCEL is present (use the existing
identifiers nitro.options.preset, isVercel, and process.env['VERCEL']).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3d80f0f2-1342-4278-bea6-dc78b8466827

📥 Commits

Reviewing files that changed from the base of the PR and between 6db73b9 and 2e72570.

📒 Files selected for processing (1)

• packages/platform/src/lib/nitro/analog-nitro-plugin.ts