vinext 1.0.0-beta.5 → 1.0.0-beta.7

package/README.md

@@ -2,6 +2,8 @@
 
 Run Next.js applications on Vite, with Cloudflare Workers as the primary deployment target.
 
+**Website:** [vinext.dev](https://vinext.dev)
+
 > **Read the announcement:** [How we rebuilt Next.js with AI in one week](https://blog.cloudflare.com/vinext/)
 
 > **Under active development.** vinext supports substantial Next.js applications today, but it is not yet a drop-in replacement for every application or production workload. Expect compatibility gaps, especially in newer App Router features, and evaluate it against your own application before adopting it.
@@ -516,12 +518,12 @@ These are deployed to Cloudflare Workers and updated on every push to `main`:
 | App Router (minimal)   | Minimal App Router on Workers                                                                                    | [app-router-cloudflare.vinext.workers.dev](https://app-router-cloudflare.vinext.workers.dev)     |
 | Pages Router (minimal) | Minimal Pages Router on Workers                                                                                  | [pages-router-cloudflare.vinext.workers.dev](https://pages-router-cloudflare.vinext.workers.dev) |
 | RealWorld API          | REST API routes example                                                                                          | [realworld-api-rest.vinext.workers.dev](https://realworld-api-rest.vinext.workers.dev)           |
-| Benchmarks Dashboard   | Build performance tracking over time (D1-backed)                                                                 | [vinext-web.vinext.workers.dev/benchmarks](https://vinext-web.vinext.workers.dev/benchmarks)     |
+| Benchmarks Dashboard   | Build performance tracking over time (D1-backed)                                                                 | [vinext.dev/benchmarks](https://vinext.dev/benchmarks)                                           |
 | App Router + Nitro     | App Router deployed via Nitro (multi-platform)                                                                   | [examples/app-router-nitro](examples/app-router-nitro)                                           |
 
 ## API coverage
 
-~94% of the Next.js 16 API surface has full or partial support. The remaining gaps are intentional stubs for deprecated features and Partial Prerendering (which Next.js 16 reworked into `"use cache"` — that directive is fully supported).
+~94% of the Next.js 16 API surface has full or partial support. The remaining gaps are intentional stubs for deprecated features, plus Partial Prerendering and Cache Components. Next.js 16 reworked PPR into `"use cache"`; vinext implements that directive for file-level and function-level caching, but full `cacheComponents` behavior is still incomplete — see [Known gaps we're working on](#known-gaps-were-working-on).
 
 > ✅ = full implementation | 🟡 = partial (runtime behavior correct, some build-time optimizations missing) | ⬜ = intentional stub/no-op
 
@@ -643,16 +645,21 @@ The cache is pluggable. The default `MemoryCacheHandler` works out of the box. S
 Instead of wiring up cache handlers imperatively from a worker entry, you can declare them in the `vinext()` plugin config. The `@vinext/cloudflare` package ships Cloudflare adapters for this:
 
 - **`kvDataAdapter()`** (`@vinext/cloudflare/cache/kv-data-adapter`) — backs the `"use cache"` data cache with a Workers KV namespace.
+- **`cdnAdapter()`** (`@vinext/cloudflare/cache/cdn-adapter`) — serves page-level ISR from the Cloudflare Workers Cache (`ctx.cache`) instead of from the origin.
+
+The two fill different slots and can be used together:
 
 ```ts
 import { defineConfig } from "vite";
 import vinext from "vinext";
+import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
 import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
 
 export default defineConfig({
   plugins: [
     vinext({
       cache: {
+        cdn: cdnAdapter(),
         data: kvDataAdapter(),
       },
     }),
@@ -670,6 +677,16 @@ The KV data adapter reads `env[binding]` at runtime, so add the matching KV name
 
 `binding` defaults to `VINEXT_KV_CACHE`, so `kvDataAdapter()` with no options works as long as that's your binding name. Other options: `appPrefix` (namespace cache keys to isolate multiple apps in one KV namespace), `ttlSeconds` (default KV `expirationTtl`, default 30 days), and `tagCacheTtlMs` (in-memory tag-invalidation cache TTL, default 5s).
 
+`cdnAdapter()` takes no options, but the Workers Cache only exposes `ctx.cache` when `cache.enabled` is set in `wrangler.jsonc`:
+
+```jsonc
+{
+  "cache": { "enabled": true },
+}
+```
+
+While the data adapter can store entries and serve HIT/STALE itself, the CDN adapter delegates serving to Cloudflare's edge: the origin renders fresh responses and tags them with `Cache-Tag`, and `revalidateTag()` / `revalidatePath()` purge the edge through `ctx.cache.purge({ tags })`. See [examples/workers-cache](examples/workers-cache) for both adapters wired up together.
+
 Each builder returns a plain, serializable `{ adapter, options }` descriptor — **it never touches the Workers runtime**, so nothing throws at build or dev time when bindings aren't available. The actual adapter (and its `env` binding lookup) is instantiated lazily on the first request.
 
 Registration is wired into **every router and runtime** — App Router and Pages Router, on Cloudflare Workers as well as the Node.js server (`vinext start`) and dev. It self-guards (instantiated once per isolate) and is resilient: if an adapter can't initialize on a given runtime (e.g. a KV binding doesn't exist on the Node server), vinext logs a warning and falls back to the default handler instead of failing requests.
@@ -713,7 +730,7 @@ We measure three things:
 - **Client bundle size** — gzipped output of each build.
 - **Dev server cold start** — 10 runs, randomized execution order. Vite's dependency optimizer cache is cleared before each run.
 
-Benchmarks run on GitHub CI runners (2-core Ubuntu) on every merge to `main`. See the launch numbers in the [announcement blog post](https://blog.cloudflare.com/vinext/) and the latest results at **[vinext-web.vinext.workers.dev/benchmarks](https://vinext-web.vinext.workers.dev/benchmarks)**.
+Benchmarks run on GitHub CI runners (2-core Ubuntu) on every merge to `main`. See the launch numbers in the [announcement blog post](https://blog.cloudflare.com/vinext/) and the latest results at **[vinext.dev/benchmarks](https://vinext.dev/benchmarks)**.
 
 <details>
 <summary>Why the bundle size difference?</summary>

package/dist/build/action-owner-manifest.d.ts

@@ -0,0 +1,42 @@
+import { AppRoute } from "../routing/app-route-graph.js";
+import { Rollup } from "vite";
+import { RscPluginManager } from "@vitejs/plugin-rsc";
+//#region src/build/action-owner-manifest.d.ts
+type ActionOwnerRoute = Pick<AppRoute, "errorPath" | "errorPaths" | "forbiddenPath" | "forbiddenPaths" | "layoutErrorPaths" | "layouts" | "loadingPath" | "loadingPaths" | "notFoundPath" | "notFoundPaths" | "pagePath" | "parallelSlots" | "pattern" | "siblingIntercepts" | "templates" | "unauthorizedPath" | "unauthorizedPaths">;
+type ActionOwnerRouteReachability = Map<string, {
+  clientReferenceImportIds: Set<string>;
+  serverReferenceIds: Set<string>;
+}>;
+type ActionOwnerModuleInfo = Pick<Rollup.ModuleInfo, "dynamicallyImportedIds" | "importedIds">;
+type ActionOwnerReferenceMaps = {
+  clientReferenceMetaMap: RscPluginManager["clientReferenceMetaMap"];
+  serverReferenceMetaMap: RscPluginManager["serverReferences"]["metaMap"];
+};
+declare function actionOwnerRouteEntryIds(route: ActionOwnerRoute): string[];
+declare function collectReachableActionReferences(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  getModuleInfo: (id: string) => ActionOwnerModuleInfo | null;
+  roots: readonly string[];
+} & ActionOwnerReferenceMaps): {
+  clientReferenceImportIds: Set<string>;
+  serverReferenceIds: Set<string>;
+};
+declare function collectRscActionReachability(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  getModuleInfo: (id: string) => ActionOwnerModuleInfo | null;
+  routes: readonly ActionOwnerRoute[];
+  sharedRoots?: readonly string[];
+} & ActionOwnerReferenceMaps): ActionOwnerRouteReachability;
+declare function resolveClientReferenceImportIds(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  resolveId: (id: string) => Promise<string | null>;
+  routeReachability: ActionOwnerRouteReachability;
+}): Promise<void>;
+declare function addClientActionReachability(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  getModuleInfo: (id: string) => ActionOwnerModuleInfo | null;
+  routeReachability: ActionOwnerRouteReachability;
+} & ActionOwnerReferenceMaps): void;
+declare function buildActionOwnerManifest(routeReachability: ActionOwnerRouteReachability): Record<string, string[]>;
+//#endregion
+export { ActionOwnerRouteReachability, actionOwnerRouteEntryIds, addClientActionReachability, buildActionOwnerManifest, collectReachableActionReferences, collectRscActionReachability, resolveClientReferenceImportIds };

package/dist/build/action-owner-manifest.js

@@ -0,0 +1,110 @@
+//#region src/build/action-owner-manifest.ts
+function actionOwnerRouteEntryIds(route) {
+	return [
+		route.pagePath,
+		...route.layouts,
+		...route.templates,
+		route.loadingPath,
+		...route.loadingPaths ?? [],
+		route.errorPath,
+		...route.layoutErrorPaths ?? [],
+		...route.errorPaths ?? [],
+		route.notFoundPath,
+		...route.notFoundPaths ?? [],
+		route.forbiddenPath,
+		...route.forbiddenPaths ?? [],
+		route.unauthorizedPath,
+		...route.unauthorizedPaths ?? [],
+		...route.parallelSlots.flatMap((slot) => [
+			slot.pagePath,
+			slot.defaultPath,
+			slot.layoutPath,
+			...slot.configLayoutPaths ?? [],
+			slot.loadingPath,
+			...slot.loadingPaths ?? [],
+			slot.errorPath,
+			slot.notFoundPath,
+			...slot.interceptingRoutes.flatMap((intercept) => [
+				intercept.pagePath,
+				...intercept.layoutPaths,
+				...intercept.loadingPaths ?? [],
+				intercept.notFoundPath
+			])
+		]),
+		...route.siblingIntercepts.flatMap((intercept) => [
+			intercept.pagePath,
+			...intercept.layoutPaths,
+			...intercept.loadingPaths ?? [],
+			intercept.notFoundPath
+		])
+	].filter((value) => typeof value === "string");
+}
+function collectReachableActionReferences(options) {
+	const canonicalizeModuleId = options.canonicalizeModuleId ?? ((id) => id);
+	const clientReferenceImportIds = /* @__PURE__ */ new Set();
+	const serverReferenceIds = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const queue = options.roots.map(canonicalizeModuleId);
+	for (let index = 0; index < queue.length; index++) {
+		const id = queue[index];
+		if (visited.has(id)) continue;
+		visited.add(id);
+		const clientReference = options.clientReferenceMetaMap[id];
+		if (clientReference) clientReferenceImportIds.add(clientReference.importId);
+		const serverReference = options.serverReferenceMetaMap.get(id);
+		if (serverReference) for (const exportName of serverReference.exportNames) serverReferenceIds.add(`${serverReference.referenceKey}#${exportName}`);
+		const info = options.getModuleInfo(id);
+		for (const importedId of [...info?.importedIds ?? [], ...info?.dynamicallyImportedIds ?? []]) if (!visited.has(importedId)) queue.push(importedId);
+	}
+	return {
+		clientReferenceImportIds,
+		serverReferenceIds
+	};
+}
+function collectRscActionReachability(options) {
+	const routeReachability = new Map(options.routes.map((route) => [route.pattern, collectReachableActionReferences({
+		canonicalizeModuleId: options.canonicalizeModuleId,
+		clientReferenceMetaMap: options.clientReferenceMetaMap,
+		getModuleInfo: options.getModuleInfo,
+		roots: actionOwnerRouteEntryIds(route),
+		serverReferenceMetaMap: options.serverReferenceMetaMap
+	})]));
+	if (options.sharedRoots?.length) routeReachability.set("*", collectReachableActionReferences({
+		canonicalizeModuleId: options.canonicalizeModuleId,
+		clientReferenceMetaMap: options.clientReferenceMetaMap,
+		getModuleInfo: options.getModuleInfo,
+		roots: options.sharedRoots,
+		serverReferenceMetaMap: options.serverReferenceMetaMap
+	}));
+	return routeReachability;
+}
+async function resolveClientReferenceImportIds(options) {
+	const canonicalizeModuleId = options.canonicalizeModuleId ?? ((id) => id);
+	for (const reachability of options.routeReachability.values()) {
+		const resolvedImportIds = /* @__PURE__ */ new Set();
+		for (const importId of reachability.clientReferenceImportIds) {
+			const resolvedId = await options.resolveId(importId) ?? importId;
+			resolvedImportIds.add(canonicalizeModuleId(resolvedId));
+		}
+		reachability.clientReferenceImportIds = resolvedImportIds;
+	}
+}
+function addClientActionReachability(options) {
+	for (const reachability of options.routeReachability.values()) {
+		const clientReachability = collectReachableActionReferences({
+			canonicalizeModuleId: options.canonicalizeModuleId,
+			clientReferenceMetaMap: options.clientReferenceMetaMap,
+			getModuleInfo: options.getModuleInfo,
+			roots: [...reachability.clientReferenceImportIds],
+			serverReferenceMetaMap: options.serverReferenceMetaMap
+		});
+		for (const actionId of clientReachability.serverReferenceIds) reachability.serverReferenceIds.add(actionId);
+	}
+}
+function buildActionOwnerManifest(routeReachability) {
+	const manifest = {};
+	for (const [pattern, reachability] of routeReachability) for (const actionId of reachability.serverReferenceIds) (manifest[actionId] ??= []).push(pattern);
+	return manifest;
+}
+//#endregion
+export { actionOwnerRouteEntryIds, addClientActionReachability, buildActionOwnerManifest, collectReachableActionReferences, collectRscActionReachability, resolveClientReferenceImportIds };

package/dist/build/clean-output.js

@@ -1,4 +1,5 @@
 import path from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
+import { isPathInsideOrEqual } from "../utils/path.js";
 import fs from "node:fs";
 //#region src/build/clean-output.ts
 function resolveOutDir(root, outDir) {
@@ -6,10 +7,6 @@ function resolveOutDir(root, outDir) {
 	if (!outDir) return path.join(resolvedRoot, "dist");
 	return path.isAbsolute(outDir) ? outDir : path.resolve(resolvedRoot, outDir);
 }
-function isPathInsideOrEqual(parent, child) {
-	const relative = path.relative(parent, child);
-	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
-}
 function shouldCleanBuildOutput(options) {
 	if (options.emptyOutDir === false) return false;
 	if (options.emptyOutDir === true) return true;

package/dist/build/client-build-config.js

@@ -86,11 +86,20 @@ function getPackageName(id) {
 */
 function createClientManualChunks(shimsDir, preserveRouteBoundaries = false) {
 	return function clientManualChunks(id) {
+		const slashedId = toSlash(id);
+		if (slashedId.startsWith(shimsDir)) {
+			if (preserveRouteBoundaries) {
+				const relativeId = slashedId.slice(shimsDir.length).split("?", 1)[0] ?? "";
+				const extensionIndex = relativeId.lastIndexOf(".");
+				const shimName = extensionIndex === -1 ? relativeId : relativeId.slice(0, extensionIndex);
+				if (ROUTE_OWNED_CLIENT_SHIMS.has(shimName)) return void 0;
+			}
+			return "vinext";
+		}
 		if (id.includes("node_modules")) {
 			const pkg = getPackageName(id);
 			if (!pkg) return void 0;
 			if (pkg === "react-dom") {
-				const slashedId = toSlash(id);
 				const sub = slashedId.slice(slashedId.lastIndexOf("react-dom/") + 10);
 				if (sub.startsWith("server.") || sub.startsWith("static.") || sub.startsWith("cjs/react-dom-server")) return "react-dom-server";
 				return "framework";
@@ -98,16 +107,6 @@ function createClientManualChunks(shimsDir, preserveRouteBoundaries = false) {
 			if (pkg === "react" || pkg === "scheduler") return "framework";
 			return;
 		}
-		const slashedId = toSlash(id);
-		if (slashedId.startsWith(shimsDir)) {
-			if (preserveRouteBoundaries) {
-				const relativeId = slashedId.slice(shimsDir.length).split("?", 1)[0] ?? "";
-				const extensionIndex = relativeId.lastIndexOf(".");
-				const shimName = extensionIndex === -1 ? relativeId : relativeId.slice(0, extensionIndex);
-				if (ROUTE_OWNED_CLIENT_SHIMS.has(shimName)) return void 0;
-			}
-			return "vinext";
-		}
 	};
 }
 function createClientFileNameConfig(assetsDir) {

package/dist/build/prerender-paths.js

@@ -9,6 +9,7 @@ import { BLOCKED_PAGES, PHASE_PRODUCTION_BUILD } from "../shims/constants.js";
 import { loadNextConfig, resolveNextConfig } from "../config/next-config.js";
 import { readPrerenderSecret } from "./server-manifest.js";
 import { startProdServer } from "../server/prod-server.js";
+import { enterPrerenderPhase } from "./prerender-phase.js";
 import { buildUrlFromParams, resolveParentParams } from "./prerender.js";
 import fs from "node:fs";
 //#region src/build/prerender-paths.ts
@@ -96,15 +97,13 @@ async function shouldStartPathDiscoveryServer(options) {
 	return false;
 }
 async function withPrerenderEndpoints(fn) {
-	const previousPrerenderFlag = process.env.VINEXT_PRERENDER;
+	const restorePrerenderPhase = enterPrerenderPhase();
 	const previousPathDiscoveryFlag = process.env[PRERENDER_PATH_DISCOVERY_ENV];
-	process.env.VINEXT_PRERENDER = "1";
 	process.env[PRERENDER_PATH_DISCOVERY_ENV] = "1";
 	try {
 		return await fn();
 	} finally {
-		if (previousPrerenderFlag === void 0) delete process.env.VINEXT_PRERENDER;
-		else process.env.VINEXT_PRERENDER = previousPrerenderFlag;
+		restorePrerenderPhase();
 		if (previousPathDiscoveryFlag === void 0) delete process.env[PRERENDER_PATH_DISCOVERY_ENV];
 		else process.env[PRERENDER_PATH_DISCOVERY_ENV] = previousPathDiscoveryFlag;
 	}

package/dist/build/prerender-phase.d.ts

@@ -0,0 +1,15 @@
+//#region src/build/prerender-phase.d.ts
+type PrerenderPhaseEnv = {
+  NEXT_PHASE?: string;
+  NODE_ENV?: string;
+  VINEXT_PRERENDER?: string;
+};
+/**
+ * Enter the same process environment phase that Next.js exposes while its
+ * static workers execute application code. The returned cleanup is nest-safe:
+ * direct prerender helpers can run inside the CLI's broader build scope without
+ * overwriting the caller's prior phase when they finish.
+ */
+declare function enterPrerenderPhase(env?: PrerenderPhaseEnv): () => void;
+//#endregion
+export { enterPrerenderPhase };

package/dist/build/prerender-phase.js

@@ -0,0 +1,37 @@
+import { PHASE_PRODUCTION_BUILD } from "../shims/constants.js";
+//#region src/build/prerender-phase.ts
+const activePrerenderPhases = /* @__PURE__ */ new WeakMap();
+/**
+* Enter the same process environment phase that Next.js exposes while its
+* static workers execute application code. The returned cleanup is nest-safe:
+* direct prerender helpers can run inside the CLI's broader build scope without
+* overwriting the caller's prior phase when they finish.
+*/
+function enterPrerenderPhase(env = process.env) {
+	let state = activePrerenderPhases.get(env);
+	if (state) state.depth += 1;
+	else {
+		state = {
+			depth: 1,
+			previousPrerenderFlag: env.VINEXT_PRERENDER,
+			previousNextPhase: env.NEXT_PHASE
+		};
+		activePrerenderPhases.set(env, state);
+	}
+	let restored = false;
+	env.VINEXT_PRERENDER = "1";
+	env.NEXT_PHASE = PHASE_PRODUCTION_BUILD;
+	return () => {
+		if (restored) return;
+		restored = true;
+		state.depth -= 1;
+		if (state.depth > 0) return;
+		activePrerenderPhases.delete(env);
+		if (state.previousPrerenderFlag === void 0) delete env.VINEXT_PRERENDER;
+		else env.VINEXT_PRERENDER = state.previousPrerenderFlag;
+		if (state.previousNextPhase === void 0) delete env.NEXT_PHASE;
+		else env.NEXT_PHASE = state.previousNextPhase;
+	};
+}
+//#endregion
+export { enterPrerenderPhase };

package/dist/build/prerender-server-entry.js

@@ -11,9 +11,9 @@ import { startProdServer } from "../server/prod-server.js";
 * vinext production server on an ephemeral port and reports it to the parent
 * over IPC. The parent then load-balances per-route fetches across the pool.
 *
-* `VINEXT_PRERENDER` / `VINEXT_PRERENDER_OUTDIR` are passed via the fork env so
-* they are set before any module loads (some server modules read the flag at
-* import time).
+* `VINEXT_PRERENDER` / `NEXT_PHASE` / `VINEXT_PRERENDER_OUTDIR` are passed via
+* the fork env so they are set before any module loads (some server and user
+* modules read the phase at import time).
 */
 async function main() {
 	const outDir = process.env.VINEXT_PRERENDER_OUTDIR;

package/dist/build/prerender-server-pool.js

@@ -1,4 +1,5 @@
 import path from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
+import { PHASE_PRODUCTION_BUILD } from "../shims/constants.js";
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import os from "node:os";
@@ -105,6 +106,7 @@ async function startPrerenderServerPool(outDir, size, entry = WORKER_ENTRY) {
 				env: {
 					...process.env,
 					VINEXT_PRERENDER: "1",
+					NEXT_PHASE: PHASE_PRODUCTION_BUILD,
 					VINEXT_PRERENDER_OUTDIR: outDir
 				},
 				stdio: [

package/dist/build/prerender.d.ts

@@ -1,6 +1,6 @@
+import { AppRoute } from "../routing/app-route-graph.js";
 import { ResolvedNextConfig } from "../config/next-config.js";
 import { Route } from "../routing/pages-router.js";
-import { AppRoute } from "../routing/app-route-graph.js";
 import { MetadataFileRoute } from "../server/metadata-routes.js";
 import { readPrerenderSecret } from "./server-manifest.js";
 import { Server } from "node:http";
@@ -27,11 +27,15 @@ type PrerenderRouteResult = {
    */
   path?: string;
   /** Which router produced this route. Used by cache seeding. */
-  router: "app" | "pages";
+  router: "app" | "pages" | "metadata";
   /** Response headers that must be replayed with the prerendered artifact. */
-  headers?: Record<string, string>;
+  headers?: Record<string, string | string[]>;
+  /** Original HTTP status for prerendered App Route-style responses. */
+  responseStatus?: number;
   /** Cache tags collected while rendering this route. */
   tags?: string[];
+  /** Raw app-tree segments used to derive App Route implicit tags. */
+  routeSegments?: string[];
   /** Set to true when this is a PPR fallback shell. */
   fallback?: boolean;
 } | {

package/dist/build/prerender.js

@@ -1,7 +1,7 @@
 import path from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
 import { createValidFileMatcher, findFileWithExtensions } from "../routing/file-matcher.js";
 import { VINEXT_PRERENDER_ROUTE_PARAMS_HEADER, VINEXT_PRERENDER_SECRET_HEADER, VINEXT_PRERENDER_SPECULATIVE_HEADER } from "../utils/protocol-headers.js";
-import { NEXT_CACHE_TAGS_HEADER, VINEXT_PRERENDER_CACHE_LIFE_HEADER } from "../server/headers.js";
+import { NEXT_CACHE_TAGS_HEADER, VINEXT_METADATA_ROUTE_CACHE_HEADER, VINEXT_PRERENDER_CACHE_LIFE_HEADER, VINEXT_PRERENDER_METADATA_ROUTES_PATH, VINEXT_PRERENDER_RENDER_ERROR_HEADER } from "../server/headers.js";
 import { classifyAppRoute, classifyPagesRoute, getAppRouteRenderEntryPath } from "./report.js";
 import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
 import { NoOpCacheHandler, getCacheHandler, setCacheHandler } from "../shims/cache-handler.js";
@@ -15,9 +15,12 @@ import { navigationRuntimeRscBootstrapExpression } from "../server/app-ssr-strea
 import { encodePrerenderRouteParams, serializePrerenderRouteParamsHeader } from "../server/prerender-route-params.js";
 import { readPrerenderSecret } from "./server-manifest.js";
 import { createAppPprFallbackShells, markAppPprDynamicFallbackShellHtml } from "../server/app-ppr-fallback-shell.js";
-import { getOutputPath, getRscOutputPath } from "../utils/prerender-output-paths.js";
+import { getAppRouteOutputPath, getOutputPath, getRscOutputPath } from "../utils/prerender-output-paths.js";
 import { startProdServer } from "../server/prod-server.js";
 import { prerenderPoolAvailable, resolvePrerenderPoolSize, startPrerenderServerPool } from "./prerender-server-pool.js";
+import { enterPrerenderPhase } from "./prerender-phase.js";
+import { buildAppRouteCacheValue } from "../server/app-route-handler-response.js";
+import { isMetadataResponseCacheable } from "../server/metadata-route-cache-policy.js";
 import fs from "node:fs";
 import os from "node:os";
 //#region src/build/prerender.ts
@@ -265,8 +268,7 @@ async function prerenderPages({ routes, apiRoutes, pagesDir, outDir, config, mod
 	});
 	const previousHandler = getCacheHandler();
 	setCacheHandler(new NoOpCacheHandler());
-	const previousPrerenderFlag = process.env.VINEXT_PRERENDER;
-	process.env.VINEXT_PRERENDER = "1";
+	const restorePrerenderPhase = enterPrerenderPhase();
 	let ownedProdServerHandle = null;
 	let renderPool = null;
 	try {
@@ -497,11 +499,13 @@ async function prerenderPages({ routes, apiRoutes, pagesDir, outDir, config, mod
 		});
 		return { routes: results };
 	} finally {
-		if (renderPool) await renderPool.close();
-		setCacheHandler(previousHandler);
-		if (previousPrerenderFlag === void 0) delete process.env.VINEXT_PRERENDER;
-		else process.env.VINEXT_PRERENDER = previousPrerenderFlag;
-		if (ownedProdServerHandle) await new Promise((resolve) => ownedProdServerHandle.server.close(() => resolve()));
+		try {
+			if (renderPool) await renderPool.close();
+			setCacheHandler(previousHandler);
+			if (ownedProdServerHandle) await new Promise((resolve) => ownedProdServerHandle.server.close(() => resolve()));
+		} finally {
+			restorePrerenderPhase();
+		}
 	}
 }
 /**
@@ -530,8 +534,7 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 	fs.mkdirSync(outDir, { recursive: true });
 	const previousHandler = getCacheHandler();
 	setCacheHandler(new NoOpCacheHandler());
-	const previousPrerenderFlag = process.env.VINEXT_PRERENDER;
-	process.env.VINEXT_PRERENDER = "1";
+	const restorePrerenderPhase = enterPrerenderPhase();
 	const serverDir = path.dirname(rscBundlePath);
 	let rscHandler;
 	let staticParamsMap = {};
@@ -743,14 +746,85 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 				isSpeculative: false
 			});
 		}
+		if (metadataRoutes.length > 0) {
+			const response = await fetch(`${baseUrl}${VINEXT_PRERENDER_METADATA_ROUTES_PATH}`, { headers: secretHeaders });
+			const text = await response.text();
+			if (!response.ok) throw new Error(`[vinext] Failed to enumerate prerenderable metadata routes: ${parsePrerenderEndpointError(text)}`);
+			const metadataEntries = JSON.parse(text);
+			if (!Array.isArray(metadataEntries)) throw new Error("[vinext] Invalid prerender metadata route response");
+			const queuedMetadataPaths = /* @__PURE__ */ new Set();
+			for (const metadataEntry of metadataEntries) {
+				if (typeof metadataEntry !== "object" || metadataEntry === null || typeof Reflect.get(metadataEntry, "path") !== "string" || typeof Reflect.get(metadataEntry, "routePattern") !== "string" || !Array.isArray(Reflect.get(metadataEntry, "routeSegments"))) continue;
+				const { path: metadataPath, routePattern, routeSegments } = metadataEntry;
+				if (!metadataPath.startsWith("/") || !routePattern.startsWith("/") || routeSegments.some((segment) => typeof segment !== "string") || queuedMetadataPaths.has(metadataPath)) continue;
+				queuedMetadataPaths.add(metadataPath);
+				urlsToRender.push({
+					kind: "metadata",
+					metadataRouteSegments: routeSegments,
+					urlPath: metadataPath,
+					routePattern,
+					prerenderRouteParams: null,
+					revalidate: false,
+					isSpeculative: false
+				});
+			}
+		}
 		/**
 		* Render a single URL and return its result.
 		* `onProgress` is intentionally not called here; the outer loop calls it
 		* exactly once per URL after this function returns, keeping the callback
 		* at a single, predictable call site.
 		*/
-		async function renderUrl({ urlPath, routePattern, prerenderRouteParams, revalidate, isSpeculative, isFallback }) {
+		async function renderUrl({ kind, metadataRouteSegments, urlPath, routePattern, prerenderRouteParams, revalidate, isSpeculative, isFallback }) {
 			try {
+				if (kind === "metadata") {
+					const request = new Request(`http://localhost${config.basePath ?? ""}${urlPath}`);
+					const response = await runWithHeadersContext(headersContextFromRequest(request), () => rscHandler(request));
+					if (!response.ok) {
+						const fatal = response.headers.get(VINEXT_PRERENDER_RENDER_ERROR_HEADER) === "1";
+						await response.body?.cancel();
+						return {
+							route: routePattern,
+							status: "error",
+							error: `Metadata route returned ${response.status}`,
+							...fatal ? { fatal: true } : {}
+						};
+					}
+					const cacheControl = response.headers.get("cache-control") ?? "";
+					if (!isMetadataResponseCacheable(response)) {
+						await response.body?.cancel();
+						return {
+							route: routePattern,
+							status: "skipped",
+							reason: "dynamic"
+						};
+					}
+					const requestCacheLife = readPrerenderCacheLifeHeader(response.headers);
+					const collectedTags = readPrerenderCacheTagsHeader(response.headers);
+					const cacheValue = await buildAppRouteCacheValue(response);
+					cacheValue.headers[VINEXT_METADATA_ROUTE_CACHE_HEADER] = "1";
+					const outputPath = getAppRouteOutputPath(urlPath);
+					const fullPath = path.join(outDir, outputPath);
+					fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+					fs.writeFileSync(fullPath, new Uint8Array(cacheValue.body));
+					const renderedCacheControl = resolveRenderedCacheControl(requestCacheLife ?? {}, cacheControl, config.expireTime);
+					const renderedRevalidate = renderedCacheControl.revalidate ?? false;
+					const renderedStale = resolveClientStaleTimeSeconds(requestCacheLife ?? void 0);
+					return {
+						route: routePattern,
+						...urlPath === routePattern ? {} : { path: urlPath },
+						status: "rendered",
+						outputFiles: [outputPath],
+						revalidate: renderedRevalidate,
+						...typeof renderedRevalidate === "number" ? { expire: renderedCacheControl.expire } : {},
+						...renderedStale === void 0 ? {} : { stale: renderedStale },
+						router: "metadata",
+						headers: cacheValue.headers,
+						responseStatus: cacheValue.status,
+						routeSegments: metadataRouteSegments ?? [],
+						tags: collectedTags
+					};
+				}
 				const prerenderRouteParamsHeader = serializePrerenderRouteParamsHeader(prerenderRouteParams);
 				const htmlHeaders = new Headers();
 				if (prerenderRouteParamsHeader !== null) htmlHeaders.set(VINEXT_PRERENDER_ROUTE_PARAMS_HEADER, prerenderRouteParamsHeader);
@@ -762,6 +836,7 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 					const linkHeader = response.headers.get("link");
 					const responseCacheLife = readPrerenderCacheLifeHeader(response.headers);
 					const cacheTags = readPrerenderCacheTagsHeader(response.headers);
+					const fatal = response.headers.get(VINEXT_PRERENDER_RENDER_ERROR_HEADER) === "1";
 					if (!response.ok || cacheControl.includes("no-store")) {
 						await response.body?.cancel();
 						return {
@@ -771,7 +846,8 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 							ok: response.ok,
 							requestCacheLife: null,
 							tags: [],
-							status: response.status
+							status: response.status,
+							fatal
 						};
 					}
 					const html = await response.text();
@@ -783,12 +859,13 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 						ok: true,
 						requestCacheLife: responseCacheLife ?? processCacheLife,
 						status: response.status,
-						tags: cacheTags
+						tags: cacheTags,
+						fatal: false
 					};
 				});
 				const htmlCacheControl = htmlRender.cacheControl;
 				if (!htmlRender.ok) {
-					if (isSpeculative) return {
+					if (isSpeculative && !htmlRender.fatal) return {
 						route: routePattern,
 						status: "skipped",
 						reason: "dynamic"
@@ -796,7 +873,8 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 					return {
 						route: routePattern,
 						status: "error",
-						error: `RSC handler returned ${htmlRender.status}`
+						error: `RSC handler returned ${htmlRender.status}`,
+						...htmlRender.fatal ? { fatal: true } : {}
 					};
 				}
 				if (htmlCacheControl.includes("no-store")) return {
@@ -919,11 +997,13 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 			...outputFiles.length > 0 ? { outputFiles } : {}
 		};
 	} finally {
-		if (renderPool) await renderPool.close();
-		setCacheHandler(previousHandler);
-		if (previousPrerenderFlag === void 0) delete process.env.VINEXT_PRERENDER;
-		else process.env.VINEXT_PRERENDER = previousPrerenderFlag;
-		if (ownedProdServerHandle) await new Promise((resolve) => ownedProdServerHandle.server.close(() => resolve()));
+		try {
+			if (renderPool) await renderPool.close();
+			setCacheHandler(previousHandler);
+			if (ownedProdServerHandle) await new Promise((resolve) => ownedProdServerHandle.server.close(() => resolve()));
+		} finally {
+			restorePrerenderPhase();
+		}
 	}
 }
 function resolveRenderedCacheControl(requestCacheLife, cacheControl, fallbackExpireSeconds) {
@@ -991,7 +1071,9 @@ function writePrerenderIndex(routes, outDir, options) {
 			...typeof r.stale === "number" ? { stale: r.stale } : {},
 			router: r.router,
 			...r.tags && r.tags.length > 0 ? { tags: r.tags } : {},
+			...r.routeSegments ? { routeSegments: r.routeSegments } : {},
 			...r.headers ? { headers: r.headers } : {},
+			...typeof r.responseStatus === "number" ? { responseStatus: r.responseStatus } : {},
 			...r.path ? { path: r.path } : {},
 			...r.fallback ? { fallback: true } : {}
 		};

package/dist/build/report.d.ts

@@ -1,6 +1,6 @@
+import { AppRoute } from "../routing/app-route-graph.js";
 import { LayoutBuildClassification } from "./layout-classification-types.js";
 import { Route } from "../routing/pages-router.js";
-import { AppRoute } from "../routing/app-route-graph.js";
 import { PrerenderResult } from "./prerender.js";
 //#region src/build/report.d.ts
 type RouteType = "static" | "isr" | "ssr" | "unknown" | "api";

package/dist/build/route-classification-manifest.d.ts

@@ -1,5 +1,5 @@
-import { ClassificationReason, ModuleGraphStaticReason } from "./layout-classification-types.js";
 import { AppRoute } from "../routing/app-route-graph.js";
+import { ClassificationReason, ModuleGraphStaticReason } from "./layout-classification-types.js";
 //#region src/build/route-classification-manifest.d.ts
 type Layer1Class = "static" | "dynamic";
 type RouteManifestEntry = {