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

Closes #2035
Closes #2188

BREAKING CHANGES

`@analogjs/vite-plugin-nitro` → `nitro/vite`
  
  `@analogjs/platform`'s `analog()` now bundles Nitro v3's first-party `nitro/vite` plugin instead of `@analogjs/vite-plugin-nitro`. Standalone users
  (those who used `@analogjs/vite-plugin-nitro` directly) must install `nitro` as a dev dep and add `nitro()` to their Vite plugin chain alongside `analog()`.
  
BEFORE:

```ts
  // vite.config.ts
  import analog from '@analogjs/platform';
  import { defineConfig } from 'vite';

  export default defineConfig({
    plugins: [analog({ /* ... */ })],
  });
```

AFTER:

```ts
  // vite.config.ts
  import analog from '@analogjs/platform';
  import angular from '@analogjs/vite-plugin-angular';
  import { nitro } from 'nitro/vite';
  import { defineConfig } from 'vite';

  export default defineConfig({
    plugins: [
      analog({ /* ... */ }),
      angular({ /* ... vite object */ }),
      nitro({ /* ... nitro object*/ })
    ],
  });
```

Author: brandonroberts

.gitignore

@@ -62,6 +62,7 @@ stats.html
 
 # Nitro
 .nitro
+.output
 /migrations.json
 
 /.env
@@ -85,4 +86,4 @@ gradle.properties
 .cursor
 .claude
 gradle.properties
-*.tsbuildinfo
+*.tsbuildinfo

apps/analog-app/package.json

@@ -13,6 +13,7 @@
     "@analogjs/platform": "workspace:*",
     "@analogjs/storybook-angular": "workspace:*",
     "@analogjs/vite-plugin-angular": "workspace:*",
-    "@analogjs/vitest-angular": "workspace:*"
+    "@analogjs/vitest-angular": "workspace:*",
+    "nitro": "catalog:"
   }
 }

apps/analog-app/project.json

@@ -7,19 +7,14 @@
   "tags": [],
   "targets": {
     "build": {
-      "executor": "@nx/vite:build",
+      "executor": "@analogjs/platform:vite",
       "dependsOn": [
         "platform:build",
         "router:build",
         "my-package:build",
         "top-bar:build"
       ],
-      "outputs": [
-        "{options.outputPath}",
-        "{workspaceRoot}/dist/apps/analog-app/.nitro",
-        "{workspaceRoot}/dist/apps/analog-app/ssr",
-        "{workspaceRoot}/dist/apps/analog-app/analog"
-      ],
+      "outputs": ["{workspaceRoot}/dist/apps/analog-app/analog"],
       "options": {
         "configFile": "apps/analog-app/vite.config.ts",
         "outputPath": "dist/apps/analog-app/client"

apps/analog-app/vite.config.ts

@@ -1,6 +1,8 @@
 /// <reference types="vitest" />
 
-import analog from '@analogjs/platform';
+import analog, { discoverLibraryRoutes, pageGlobs } from '@analogjs/platform';
+import angular from '@analogjs/vite-plugin-angular';
+import { nitro } from 'nitro/vite';
 import { resolve } from 'node:path';
 import { defineConfig, PluginOption } from 'vite';
 import { getWorkspaceDependencyExcludes } from '../../tools/vite/get-workspace-dependency-excludes.js';
@@ -37,12 +39,15 @@ export default defineConfig(async ({ mode, command }) => {
           },
         ];
 
+  const discoveredLibs = discoverLibraryRoutes(resolve(__dirname, '../..'));
+  const explicitLibPages = useBuiltWorkspaceLibs
+    ? []
+    : ['/libs/my-package/src/**/*.ts', '/libs/top-bar/src/**/*.ts'];
+
   return {
     root: __dirname,
     publicDir: 'src/public',
     build: {
-      outDir: '../../dist/apps/analog-app/client',
-      emptyOutDir: true,
       reportCompressedSize: true,
       target: ['es2020'],
     },
@@ -58,11 +63,9 @@ export default defineConfig(async ({ mode, command }) => {
         content: {
           highlighter: 'prism',
         },
-        include: useBuiltWorkspaceLibs
-          ? []
-          : ['/libs/my-package/src/**/*.ts', '/libs/top-bar/src/**/*.ts'],
-        discoverRoutes: true,
-        fileReplacements,
+        additionalPagesDirs: discoveredLibs.additionalPagesDirs,
+        additionalContentDirs: discoveredLibs.additionalContentDirs,
+        additionalAPIDirs: discoveredLibs.additionalAPIDirs,
         prerender: {
           routes: [
             '/',
@@ -79,23 +82,25 @@ export default defineConfig(async ({ mode, command }) => {
             host: base,
           },
         },
-        inlineStylesExtension: 'scss',
-        fastCompile: true,
         experimental: {
           typedRouter: true,
         },
-        nitro: {
-          routeRules: {
-            '/client': {
-              ssr: false,
-            },
-            '/cart/**': {
-              ssr: false,
-            },
-            '/404.html': {
-              ssr: false,
-            },
-          },
+      }),
+      angular({
+        include: [
+          ...explicitLibPages,
+          ...pageGlobs(discoveredLibs.additionalPagesDirs),
+        ],
+        additionalContentDirs: discoveredLibs.additionalContentDirs,
+        inlineStylesExtension: 'scss',
+        fileReplacements,
+        fastCompile: true,
+      }),
+      nitro({
+        routeRules: {
+          '/client': { ssr: false },
+          '/cart/**': { ssr: false },
+          '/404.html': { ssr: false },
         },
       }),
       {

apps/blog-app/package.json

@@ -7,6 +7,8 @@
     "@analogjs/router": "workspace:*"
   },
   "devDependencies": {
-    "@analogjs/platform": "workspace:*"
+    "@analogjs/platform": "workspace:*",
+    "@analogjs/vite-plugin-angular": "workspace:*",
+    "nitro": "catalog:"
   }
 }

apps/blog-app/project.json

@@ -7,14 +7,9 @@
   "tags": [],
   "targets": {
     "build": {
-      "executor": "@nx/vite:build",
+      "executor": "@analogjs/platform:vite",
       "dependsOn": ["platform:build", "router:build", "content:build"],
-      "outputs": [
-        "{options.outputPath}",
-        "{workspaceRoot}/dist/apps/blog-app/.nitro",
-        "{workspaceRoot}/dist/apps/blog-app/ssr",
-        "{workspaceRoot}/dist/apps/blog-app/analog"
-      ],
+      "outputs": ["{workspaceRoot}/dist/apps/blog-app/analog"],
       "options": {
         "configFile": "apps/blog-app/vite.config.ts",
         "outputPath": "dist/apps/blog-app/client"

…ps/blog-app/src/server/routes/rss.xml.ts …log-app/src/server/routes/api/rss.xml.tsapps/blog-app/src/server/routes/rss.xml.ts renamed to apps/blog-app/src/server/routes/api/rss.xml.ts apps/blog-app/src/server/routes/rss.xml.ts renamed to apps/blog-app/src/server/routes/api/rss.xml.ts

@@ -1,6 +1,8 @@
 /// <reference types="vitest" />
 
 import analog, { type PrerenderContentFile } from '@analogjs/platform';
+import angular from '@analogjs/vite-plugin-angular';
+import { nitro } from 'nitro/vite';
 import { defineConfig } from 'vite';
 import { getWorkspaceDependencyExcludes } from '../../tools/vite/get-workspace-dependency-excludes.js';
 
@@ -26,14 +28,11 @@ export default defineConfig(() => {
       exclude: getWorkspaceDependencyExcludes(__dirname),
     },
     build: {
-      outDir: '../../dist/apps/blog-app/client',
-      emptyOutDir: true,
       reportCompressedSize: true,
       target: ['es2020'],
     },
     plugins: [
       analog({
-        liveReload: true,
         content: {
           highlighter: 'shiki',
           shikiOptions: {
@@ -84,11 +83,14 @@ export default defineConfig(() => {
             host: 'https://analog-blog.netlify.app',
           },
         },
-        nitro: {
-          prerender: {
-            autoSubfolderIndex: false,
-            failOnError: true,
-          },
+      }),
+      angular({
+        liveReload: true,
+      }),
+      nitro({
+        prerender: {
+          autoSubfolderIndex: false,
+          failOnError: true,
         },
       }),
     ],

…og-app/src/server/routes/v1/[...slug].ts …pp/src/server/routes/api/v1/[...slug].tsapps/blog-app/src/server/routes/v1/[...slug].ts renamed to apps/blog-app/src/server/routes/api/v1/[...slug].ts apps/blog-app/src/server/routes/v1/[...slug].ts renamed to apps/blog-app/src/server/routes/api/v1/[...slug].ts

@@ -37,6 +37,172 @@ Analog v3 no longer supports Angular v16. Upgrade the workspace to Angular v17 o
 
 Analog SFC support was removed and `.agx` files are no longer supported. Replace any remaining SFC usage with standard Angular components, markdown content files, or route/page files that use the current Analog conventions.
 
+### `analog()`, `angular()`, and `nitro()` are now separate plugins
+
+Analog v3 splits the Vite plugin chain into three explicit calls. `analog()` no longer internally invokes `@analogjs/vite-plugin-angular` or `nitro/vite` — you call them yourself. Pass each plugin only the options it owns.
+
+`@analogjs/platform` v3 owns its own Nitro orchestration via `nitro/vite` directly and no longer composes `@analogjs/vite-plugin-nitro` internally. `@analogjs/vite-plugin-nitro` continues to ship as a standalone package for projects that want to wire it themselves; users coming from a v2 `analog({ nitro: {...} })` shape should migrate to the separated shape below (analog + angular + nitro from `nitro/vite`).
+
+Before:
+
+```ts
+import { defineConfig } from 'vite';
+import analog from '@analogjs/platform';
+
+export default defineConfig(() => ({
+  plugins: [
+    analog({
+      ssr: true,
+      apiPrefix: 'api',
+      vite: {
+        inlineStylesExtension: 'scss',
+        fastCompile: true,
+      },
+      fileReplacements: [
+        { replace: 'src/environment.ts', with: 'src/environment.prod.ts' },
+      ],
+      nitro: {
+        routeRules: { '/admin/**': { ssr: false } },
+      },
+      prerender: {
+        routes: ['/', '/about'],
+      },
+    }),
+  ],
+}));
+```
+
+After:
+
+```ts
+import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
+import analog from '@analogjs/platform';
+import angular from '@analogjs/vite-plugin-angular';
+import { nitro } from 'nitro/vite';
+
+export default defineConfig(() => ({
+  server: {
+    // Vite 8's strict fs only allows reads under config.root; nitro/vite's
+    // env-runner reaches pnpm content-hash paths at the workspace root
+    // when loading its own dev runtime.
+    fs: { allow: [resolve(__dirname, '../..')] },
+  },
+  plugins: [
+    analog({
+      ssr: true,
+      apiPrefix: 'api',
+      prerender: {
+        routes: ['/', '/about'],
+      },
+    }),
+    angular({
+      workspaceRoot: resolve(__dirname, '../..'),
+      inlineStylesExtension: 'scss',
+      fastCompile: true,
+      fileReplacements: [
+        { replace: 'src/environment.ts', with: 'src/environment.prod.ts' },
+      ],
+    }),
+    nitro({
+      routeRules: { '/admin/**': { ssr: false } },
+    }),
+  ],
+}));
+```
+
+Add `@analogjs/vite-plugin-angular` and `nitro` to the app's `devDependencies`:
+
+```json
+{
+  "devDependencies": {
+    "@analogjs/platform": "...",
+    "@analogjs/vite-plugin-angular": "...",
+    "nitro": "..."
+  }
+}
+```
+
+#### Options that moved off `analog()`
+
+These options used to live on `analog()`. Pass them to `angular()` or `nitro()` directly:
+
+| v2 location                                                                                                                                      | v3 location                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| `analog({ vite: {...} })`                                                                                                                        | spread directly into `angular({...})`                           |
+| `analog({ jit })`, `disableTypeChecking`, `liveReload`, `inlineStylesExtension`, `fileReplacements`, `fastCompile`, `fastCompileMode`, `include` | `angular({...})`                                                |
+| `analog({ tailwindCss: {...} })`                                                                                                                 | `angular({ tailwindCss: {...} })`                               |
+| `analog({ experimental: { useAngularCompilationAPI: true } })`                                                                                   | `angular({ experimental: { useAngularCompilationAPI: true } })` |
+| `analog({ experimental: { stylePipeline: { angularPlugins: [...] } } })`                                                                         | `angular({ stylePipeline: { plugins: [...] } })`                |
+| `analog({ nitro: {...} })`                                                                                                                       | `nitro({...})` (first arg)                                      |
+| `analog({ vite: false })`                                                                                                                        | drop `angular()` from the plugins array                         |
+
+`analog()` retains `ssr`, `apiPrefix`, `entryServer`, `content`, `prerender`, `i18n`, `discoverRoutes`, `additionalPagesDirs`/`additionalContentDirs`/`additionalAPIDirs`, `debug`, and `experimental.typedRouter`/`experimental.stylePipeline`.
+
+#### Workspace library globs
+
+If your v2 config used `discoverRoutes: true` to compile workspace library pages, the same helper is now exported from `@analogjs/platform`. Call it once and feed the result to both `analog()` and `angular()`:
+
+```ts
+import analog, { discoverLibraryRoutes, pageGlobs } from '@analogjs/platform';
+import angular from '@analogjs/vite-plugin-angular';
+
+const libs = discoverLibraryRoutes(resolve(__dirname, '../..'));
+
+plugins: [
+  analog({
+    additionalPagesDirs: libs.additionalPagesDirs,
+    additionalContentDirs: libs.additionalContentDirs,
+    additionalAPIDirs: libs.additionalAPIDirs,
+  }),
+  angular({
+    include: pageGlobs(libs.additionalPagesDirs),
+    additionalContentDirs: libs.additionalContentDirs,
+  }),
+  nitro(),
+];
+```
+
+#### Nx build target
+
+If your app uses `@nx/vite:build`, switch it to `nx:run-commands` invoking `vite build`. `@nx/vite:build` iterates `builder.environments` but doesn't call `builder.buildApp()` — and `nitro/vite`'s prerender + final Nitro env build orchestration lives in the `buildApp` hook. Without the CLI's `buildApp` invocation, no prerender runs and the SSR/Nitro env outputs are skipped.
+
+Before (`apps/<app>/project.json`):
+
+```json
+{
+  "build": {
+    "executor": "@nx/vite:build",
+    "outputs": [
+      "{options.outputPath}",
+      "{workspaceRoot}/dist/apps/<app>/.nitro",
+      "{workspaceRoot}/dist/apps/<app>/ssr",
+      "{workspaceRoot}/dist/apps/<app>/analog"
+    ],
+    "options": {
+      "configFile": "apps/<app>/vite.config.ts",
+      "outputPath": "dist/apps/<app>/client"
+    }
+  }
+}
+```
+
+After:
+
+```json
+{
+  "build": {
+    "executor": "nx:run-commands",
+    "outputs": ["{workspaceRoot}/apps/<app>/.output"],
+    "options": {
+      "command": "vite build -c apps/<app>/vite.config.ts"
+    }
+  }
+}
+```
+
+Also drop the top-level `build.outDir` override in `vite.config.ts`. Under `nitro/vite`, the client environment's output is relocated to `<rootDir>/.output/public` by Nitro; the legacy `dist/apps/<app>/client` override no longer matches the active output path.
+
 ### Content rendering now requires an explicit highlighter
 
 If your app renders markdown content, configure the content highlighter through the `analog()` plugin in `vite.config.ts`. New blog templates already do this, but older full-stack apps often do not.
@@ -152,6 +318,11 @@ Keep automated migration tooling focused on the breaking changes above:
 
 - require Angular v17 or newer before applying v3 changes
 - replace deep or internal imports with public package entrypoints
+- split `analog()` into `analog() + angular() + nitro()`, moving each option to the plugin that now owns it (see [plugin separation](#analog-angular-and-nitro-are-now-separate-plugins))
+- @analogjs/platform no longer composes @analogjs/vite-plugin-nitro internally; direct importers can either migrate to `@analogjs/platform` + `nitro/vite` (recommended) or continue using @analogjs/vite-plugin-nitro standalone
+- add `@analogjs/vite-plugin-angular` to app `devDependencies` (the separated shape imports it directly). `nitro` is picked up as a transitive of `@analogjs/platform` for npm/yarn; pnpm users must add it to `devDependencies` explicitly
+- replace `@nx/vite:build` with `nx:run-commands` invoking `vite build -c apps/<app>/vite.config.ts`; drop the legacy `build.outDir` override and update `outputs` to `apps/<app>/.output`
+- add `server.fs.allow` pointing at the workspace root in `vite.config.ts` so Vite 8's strict fs allows nitro/vite's env runner to load its own dev runtime through pnpm content-hash paths
 - add explicit `analog({ content: { highlighter: 'shiki' } })` config when the app renders markdown content
 - add `withContentRoutes()` from `@analogjs/router/content` when the app uses markdown page routes
 - flag `analog({ i18n: ... })`, `provideI18n()`, `injectSwitchLocale()`, `loadTranslationsRuntime()`, or content locale helpers as removed v3 APIs