vinext 0.1.7 → 0.2.0

package/README.md

@@ -49,30 +49,37 @@ Replace `next` with `vinext` in your scripts:
 ```bash
 vinext dev          # Development server with HMR
 vinext build        # Production build
-vinext deploy       # Build and deploy to Cloudflare Workers
+npx @vinext/cloudflare deploy  # Build and deploy to Cloudflare Workers
 ```
 
+With Vite+, use `vpx @vinext/cloudflare deploy`, or
+`vp exec vinext-cloudflare deploy` when running the locally installed bin.
+
 vinext auto-detects your `app/` or `pages/` directory, loads `next.config.js`, and configures Vite automatically. No `vite.config.ts` required for basic usage.
 
 Your existing `pages/`, `app/`, `next.config.js`, and `public/` directories work as-is. Run `vinext check` first to scan for known compatibility issues, or use `vinext init` to [automate the full migration](#migrating-an-existing-nextjs-project).
 
 ### CLI reference
 
-| Command         | Description                                                             |
-| --------------- | ----------------------------------------------------------------------- |
-| `vinext dev`    | Start dev server with HMR                                               |
-| `vinext build`  | Production build (multi-environment for App Router: RSC + SSR + client) |
-| `vinext start`  | Start local production server for testing                               |
-| `vinext deploy` | Build and deploy to Cloudflare Workers                                  |
-| `vinext init`   | Migrate a Next.js project to run under vinext                           |
-| `vinext check`  | Scan your Next.js app for compatibility issues before migrating         |
-| `vinext lint`   | Delegate to eslint or oxlint                                            |
+| Command                            | Description                                                             |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| `vinext dev`                       | Start dev server with HMR                                               |
+| `vinext build`                     | Production build (multi-environment for App Router: RSC + SSR + client) |
+| `vinext start`                     | Start local production server for testing                               |
+| `npx @vinext/cloudflare deploy`    | Build and deploy to Cloudflare Workers                                  |
+| `vp exec vinext-cloudflare deploy` | Build and deploy to Cloudflare Workers with Vite+                       |
+| `vinext init`                      | Migrate a Next.js project to run under vinext                           |
+| `vinext check`                     | Scan your Next.js app for compatibility issues before migrating         |
+| `vinext lint`                      | Delegate to eslint or oxlint                                            |
 
 Options: `-p / --port <port>`, `-H / --hostname <host>`, `--turbopack` (accepted, no-op).
 
-`vinext deploy` options: `--preview`, `--env <name>`, `--name <name>`, `--skip-build`, `--dry-run`, `--experimental-tpr`.
+`@vinext/cloudflare deploy` options: `--preview`, `--env <name>`, `--name <name>`, `--skip-build`, `--dry-run`, `--experimental-tpr`.
+
+`vinext init` prompts for a deployment target, defaulting to Cloudflare. Agents must ask the
+user which target they want, then pass `--platform=cloudflare` or `--platform=node`.
 
-`vinext init` options: `--port <port>` (default: 3001), `--skip-check`, `--force`.
+Other options: `--port <port>` (default: 3001), `--skip-check`, `--force`.
 
 If your `next.config.*` sets `output: "standalone"`, `vinext build` emits a self-hosting bundle at `dist/standalone/`. Start it with:
 
@@ -105,7 +112,9 @@ This will:
 3. Rename CJS config files (e.g. `postcss.config.js` -> `.cjs`) to avoid ESM conflicts
 4. Add `"type": "module"` to `package.json`
 5. Add `dev:vinext`, `build:vinext`, and `start:vinext` scripts to `package.json`
-6. Generate a minimal `vite.config.ts`
+6. Prompt for a deployment platform (Cloudflare by default, or Node)
+7. Generate the matching `vite.config.ts`
+8. For Cloudflare, generate `wrangler.jsonc`
 
 The migration is non-destructive -- your existing Next.js setup continues to work alongside vinext. It does not modify `next.config`, `tsconfig.json`, or any source files, and it does not remove Next.js dependencies.
 
@@ -118,7 +127,10 @@ npm run start:vinext  # Start vinext production server
 npm run dev           # Still runs Next.js as before
 ```
 
-Use `--force` to overwrite an existing `vite.config.ts`, or `--skip-check` to skip the compatibility report.
+Use `--platform=cloudflare` or `--platform=node` to skip the platform prompt. Cloudflare init
+updates an existing JavaScript or TypeScript Vite config using its AST, preserving unrelated
+settings. Use `--force` to replace an existing Node-target Vite config, or `--skip-check` to skip
+the compatibility report.
 
 ## Why
 
@@ -126,7 +138,7 @@ Vite has become the default build tool for modern web frameworks — fast HMR, a
 
 vinext is an experiment: can we reimplement the Next.js API surface on Vite, so that existing Next.js applications can run on a completely different toolchain? The answer, so far, is mostly yes.
 
-vinext works everywhere. It natively supports Cloudflare Workers (with `vinext deploy`, bindings, KV caching), and can be deployed to Vercel, Netlify, AWS, Deno Deploy, and more via the [Nitro](https://v3.nitro.build/) Vite plugin. Native support for additional platforms is [planned](https://github.com/cloudflare/vinext/issues/80).
+vinext works everywhere. It natively supports Cloudflare Workers (with `npx @vinext/cloudflare deploy` or `vp exec vinext-cloudflare deploy`, bindings, KV caching), and can be deployed to Vercel, Netlify, AWS, Deno Deploy, and more via the [Nitro](https://v3.nitro.build/) Vite plugin. Native support for additional platforms is [planned](https://github.com/cloudflare/vinext/issues/80).
 
 **Alternatives worth knowing about:**
 
@@ -173,7 +185,7 @@ Both. File-system routing, SSR, client hydration, and deployment to Cloudflare W
 Next.js 16.x. No support for deprecated APIs from older versions.
 
 **Can I deploy to AWS/Netlify/other platforms?**
-Yes. Add the [Nitro](https://v3.nitro.build/) Vite plugin alongside vinext, and you can deploy to Vercel, Netlify, AWS Amplify, Deno Deploy, Azure, and [many more](https://v3.nitro.build/deploy). See [Other platforms (via Nitro)](#other-platforms-via-nitro) for setup. For Cloudflare Workers, the native integration (`vinext deploy`) gives you the smoothest experience. Native adapters for more platforms are [planned](https://github.com/cloudflare/vinext/issues/80).
+Yes. Add the [Nitro](https://v3.nitro.build/) Vite plugin alongside vinext, and you can deploy to Vercel, Netlify, AWS Amplify, Deno Deploy, Azure, and [many more](https://v3.nitro.build/deploy). See [Other platforms (via Nitro)](#other-platforms-via-nitro) for setup. For Cloudflare Workers, the native integration (`npx @vinext/cloudflare deploy` or `vp exec vinext-cloudflare deploy`) gives you the smoothest experience. Native adapters for more platforms are [planned](https://github.com/cloudflare/vinext/issues/80).
 
 **What happens when Next.js releases a new feature?**
 We track the public Next.js API surface and add support for new stable features. Experimental or unstable Next.js features are lower priority. The plan is to add commit-level tracking of the Next.js repo so we can stay current as new versions are released.
@@ -182,16 +194,16 @@ We track the public Next.js API surface and add support for new stable features.
 
 ### Cloudflare Workers
 
-vinext has native integration with Cloudflare Workers through `@cloudflare/vite-plugin`, including bindings access via `cloudflare:workers`, KV caching, image optimization, and the `vinext deploy` one-command workflow.
+vinext has native integration with Cloudflare Workers through `@cloudflare/vite-plugin`, including bindings access via `cloudflare:workers`, KV caching, image optimization, and the `@vinext/cloudflare deploy` one-command workflow.
 
 #### Prerequisites
 
-Before running `vinext deploy` for the first time you need to authenticate with Cloudflare and tell wrangler which account to deploy to.
+Before running `npx @vinext/cloudflare deploy` for the first time you need to authenticate with Cloudflare and tell wrangler which account to deploy to.
 
 **Authentication — pick one:**
 
 - **`wrangler login`** (recommended for local development) — opens a browser window to authenticate. Run it once and wrangler caches the token.
-- **`CLOUDFLARE_API_TOKEN` env var** (CI / non-interactive) — create a token at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens) using the **Edit Cloudflare Workers** template. That template grants all the permissions `vinext deploy` needs.
+- **`CLOUDFLARE_API_TOKEN` env var** (CI / non-interactive) — create a token at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens) using the **Edit Cloudflare Workers** template. That template grants all the permissions `@vinext/cloudflare deploy` needs.
 
 **Account ID:**
 
@@ -208,16 +220,24 @@ Find your account ID in the Cloudflare dashboard URL (`dash.cloudflare.com/<acco
 
 Alternatively, set the `CLOUDFLARE_ACCOUNT_ID` environment variable instead of hardcoding it in the config file.
 
-`vinext deploy` auto-generates the necessary configuration files (`vite.config.ts`, `wrangler.jsonc`, `worker/index.ts`) if they don't exist, builds the application, and deploys to Workers.
+Run `vinext init --platform=cloudflare` first to install dependencies and create or AST-update
+`vite.config.*` and `wrangler.jsonc`. `@vinext/cloudflare deploy` then validates that setup, builds the
+application, and deploys to Workers without rewriting project configuration.
+
+Cloudflare init can also configure image optimization declaratively in the Vite config with
+`imagesOptimizer()` and add the matching Wrangler Images binding. The built-in fetch handlers register
+that optimizer at runtime; image optimization is not implemented or generated by `@vinext/cloudflare deploy`.
 
 ```bash
-vinext deploy
-vinext deploy --env staging
+npx @vinext/cloudflare deploy
+vp exec vinext-cloudflare deploy
+npx @vinext/cloudflare deploy --env staging
+vp exec vinext-cloudflare deploy --env staging
 ```
 
 Use `--env <name>` to target `wrangler.jsonc` `env.<name>`. `--preview` is shorthand for `--env preview`.
 
-The deploy command also auto-detects and fixes common migration issues:
+The init command also auto-detects and fixes common migration issues:
 
 - Adds `"type": "module"` to package.json if missing
 - Resolves tsconfig.json path aliases automatically (via `vite-tsconfig-paths`)
@@ -263,10 +283,11 @@ For TypeScript types, generate them with `wrangler types` and the `env` import w
 TPR queries Cloudflare zone analytics at deploy time to find which pages actually get traffic, pre-renders only those, and uploads them to KV cache. The result is SSG-level latency for popular pages without pre-rendering your entire site.
 
 ```bash
-vinext deploy --experimental-tpr                    # Pre-render pages covering 90% of traffic
-vinext deploy --experimental-tpr --tpr-coverage 95  # More aggressive coverage
-vinext deploy --experimental-tpr --tpr-limit 500    # Cap at 500 pages
-vinext deploy --experimental-tpr --tpr-window 48    # Use 48h of analytics
+npx @vinext/cloudflare deploy --experimental-tpr                    # Pre-render pages covering 90% of traffic
+vp exec vinext-cloudflare deploy --experimental-tpr                 # Same, with Vite+
+npx @vinext/cloudflare deploy --experimental-tpr --tpr-coverage 95  # More aggressive coverage
+npx @vinext/cloudflare deploy --experimental-tpr --tpr-limit 500    # Cap at 500 pages
+npx @vinext/cloudflare deploy --experimental-tpr --tpr-window 48    # Use 48h of analytics
 ```
 
 Requires a custom domain (zone analytics are unavailable on `*.workers.dev`) and `CLOUDFLARE_API_TOKEN` with Zone.Analytics read permission.
@@ -326,7 +347,7 @@ NITRO_PRESET=netlify npx vite build
 NITRO_PRESET=deno_deploy npx vite build
 ```
 
-> **Deploying to Cloudflare?** You can use Nitro, but the native integration (`vinext deploy` / `@cloudflare/vite-plugin`) is recommended. It provides the best developer experience with `cloudflare:workers` bindings, KV caching, image optimization, and one-command deploys.
+> **Deploying to Cloudflare?** You can use Nitro, but the native integration (`npx @vinext/cloudflare deploy`, `vp exec vinext-cloudflare deploy`, and `@cloudflare/vite-plugin`) is recommended. It provides the best developer experience with `cloudflare:workers` bindings, KV caching, image optimization, and one-command deploys.
 
 <details>
 <summary>Vercel</summary>
@@ -508,7 +529,7 @@ Load order matches Next.js (highest priority first):
 Modes:
 
 - `vinext dev` uses `development`
-- `vinext build`, `vinext start`, and `vinext deploy` use `production`
+- `vinext build`, `vinext start`, and `@vinext/cloudflare deploy` use `production`
 
 Variable expansion (`$VAR` / `${VAR}`) is supported.
 
@@ -597,7 +618,7 @@ These are gaps we'd like to close — distinct from the [intentional exclusions]
 - **Google Fonts are loaded from the CDN, not self-hosted.** No `size-adjust` fallback font metrics. Local fonts work but `@font-face` CSS is injected at runtime, not extracted at build time.
 - **Route segment config** — `runtime` and `preferredRegion` are ignored (everything runs in the same environment).
 - **Node.js production server (`vinext start`)** works for testing but is less complete than Workers deployment. Cloudflare Workers is the primary target.
-- **Native Node modules (sharp, resvg, satori, lightningcss, @napi-rs/canvas)** crash Vite's RSC dev environment. Dynamic OG image/icon routes using these work in production builds but not in dev mode. These are auto-stubbed during `vinext deploy`.
+- **Native Node modules (sharp, resvg, satori, lightningcss, @napi-rs/canvas)** crash Vite's RSC dev environment. Dynamic OG image/icon routes using these work in production builds but not in dev mode. These are auto-stubbed during `@vinext/cloudflare deploy`.
 - **`next.config.ts` `baseUrl` bare imports require Vite 8.** A `next.config.ts` that imports a bare specifier resolved through `tsconfig.json`'s `compilerOptions.baseUrl` (e.g. `import { bar } from "bar"` resolving to a local `bar.ts`) relies on Vite 8's native `resolve.tsconfigPaths` (Rolldown/oxc-resolver). On Vite 7 there is no native equivalent, so these imports are not resolved. `compilerOptions.paths` aliases (e.g. `@/foo`) work on both Vite 7 and 8. Note that if a bare import matches both a `baseUrl`-local file and an installed package of the same name, the installed package wins (vinext keeps packages externalized so CJS config plugins like `@next/mdx` keep working).
 
 ## Benchmarks

package/dist/build/inject-pregenerated-paths.d.ts

@@ -0,0 +1,4 @@
+//#region src/build/inject-pregenerated-paths.d.ts
+declare function injectPregeneratedConcretePaths(root: string): void;
+//#endregion
+export { injectPregeneratedConcretePaths };

package/dist/build/inject-pregenerated-paths.js

@@ -0,0 +1,18 @@
+import { escapeRegExp } from "../utils/regex.js";
+import { readPrerenderManifest } from "../server/prerender-manifest.js";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/build/inject-pregenerated-paths.ts
+const VINEXT_PREGEN_START = "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_START__ */";
+const VINEXT_PREGEN_END = "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_END__ */";
+const VINEXT_PREGEN_RE = new RegExp(`${escapeRegExp(VINEXT_PREGEN_START)}[\\s\\S]*?${escapeRegExp(VINEXT_PREGEN_END)}\\n?`, "g");
+function injectPregeneratedConcretePaths(root) {
+	const workerEntry = path.resolve(root, "dist", "server", "index.js");
+	if (!fs.existsSync(workerEntry)) return;
+	let code = fs.readFileSync(workerEntry, "utf-8").replace(VINEXT_PREGEN_RE, "");
+	const table = readPrerenderManifest(path.join(root, "dist", "server", "vinext-prerender.json"))?.pregeneratedConcretePaths ?? [];
+	if (table.length > 0) code = `${VINEXT_PREGEN_START}\nglobalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = ${JSON.stringify(table)};\n${VINEXT_PREGEN_END}\n` + code;
+	fs.writeFileSync(workerEntry, code);
+}
+//#endregion
+export { injectPregeneratedConcretePaths };

package/dist/build/layout-classification.js

@@ -1,6 +1,6 @@
+import { classifyLayoutSegmentConfig } from "./report.js";
 import { AppElementsWire } from "../server/app-elements-wire.js";
 import "../server/app-elements.js";
-import { classifyLayoutSegmentConfig } from "./report.js";
 import { createAppPageTreePath } from "../server/app-page-route-wiring.js";
 //#region src/build/layout-classification.ts
 /**

package/dist/build/nitro-route-rules.js

@@ -1,6 +1,6 @@
 import { apiRouter, pagesRouter } from "../routing/pages-router.js";
-import { appRouter } from "../routing/app-router.js";
 import { buildReportRows } from "./report.js";
+import { appRouter } from "../routing/app-router.js";
 //#region src/build/nitro-route-rules.ts
 /**
 * Scans the filesystem for route files and generates Nitro `routeRules` for ISR routes.

package/dist/build/pages-client-assets-module.d.ts

@@ -0,0 +1,11 @@
+import { PagesClientAssets } from "../server/pages-client-assets.js";
+
+//#region src/build/pages-client-assets-module.d.ts
+declare const PAGES_CLIENT_ASSETS_MODULE = "vinext-client-assets.js";
+declare function buildPagesClientAssetsModule(assets: PagesClientAssets): string;
+declare function writePagesClientAssetsModuleIfMissing(outputDir: string, moduleSource: string): void;
+declare function setPagesClientAssetsBuildMetadata(buildSession: string, moduleSource: string): void;
+declare function takePagesClientAssetsBuildMetadata(buildSession: string): string | null;
+declare function clearPagesClientAssetsBuildMetadata(buildSession: string): void;
+//#endregion
+export { PAGES_CLIENT_ASSETS_MODULE, buildPagesClientAssetsModule, clearPagesClientAssetsBuildMetadata, setPagesClientAssetsBuildMetadata, takePagesClientAssetsBuildMetadata, writePagesClientAssetsModuleIfMissing };

package/dist/build/pages-client-assets-module.js

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/build/pages-client-assets-module.ts
+const PAGES_CLIENT_ASSETS_MODULE = "vinext-client-assets.js";
+const pagesClientAssetsByBuildSession = /* @__PURE__ */ new Map();
+function buildPagesClientAssetsModule(assets) {
+	return `export default ${JSON.stringify(assets)};\n`;
+}
+function writePagesClientAssetsModuleIfMissing(outputDir, moduleSource) {
+	const outputPath = path.join(outputDir, PAGES_CLIENT_ASSETS_MODULE);
+	if (fs.existsSync(outputPath)) return;
+	fs.mkdirSync(outputDir, { recursive: true });
+	fs.writeFileSync(outputPath, moduleSource);
+}
+function setPagesClientAssetsBuildMetadata(buildSession, moduleSource) {
+	pagesClientAssetsByBuildSession.set(buildSession, moduleSource);
+}
+function takePagesClientAssetsBuildMetadata(buildSession) {
+	const moduleSource = pagesClientAssetsByBuildSession.get(buildSession) ?? null;
+	pagesClientAssetsByBuildSession.delete(buildSession);
+	return moduleSource;
+}
+function clearPagesClientAssetsBuildMetadata(buildSession) {
+	pagesClientAssetsByBuildSession.delete(buildSession);
+}
+//#endregion
+export { PAGES_CLIENT_ASSETS_MODULE, buildPagesClientAssetsModule, clearPagesClientAssetsBuildMetadata, setPagesClientAssetsBuildMetadata, takePagesClientAssetsBuildMetadata, writePagesClientAssetsModuleIfMissing };

package/dist/build/prerender.d.ts

@@ -22,7 +22,8 @@ type PrerenderRouteResult = {
    * Omitted for non-dynamic routes where pattern === path.
    */
   path?: string; /** Which router produced this route. Used by cache seeding. */
-  router: "app" | "pages"; /** Set to true when this is a PPR fallback shell. */
+  router: "app" | "pages"; /** Response headers that must be replayed with the prerendered artifact. */
+  headers?: Record<string, string>; /** Set to true when this is a PPR fallback shell. */
   fallback?: boolean;
 } | {
   route: string;

package/dist/build/prerender.js

@@ -1,16 +1,17 @@
 import { createValidFileMatcher, findFileWithExtensions } from "../routing/file-matcher.js";
-import { VINEXT_PRERENDER_ROUTE_PARAMS_HEADER, VINEXT_PRERENDER_SECRET_HEADER } from "../server/headers.js";
-import { normalizeStaticPathsEntry } from "../routing/route-pattern.js";
+import { VINEXT_PRERENDER_ROUTE_PARAMS_HEADER, VINEXT_PRERENDER_SECRET_HEADER } from "../utils/protocol-headers.js";
+import { classifyAppRoute, classifyPagesRoute, getAppRouteRenderEntryPath } from "./report.js";
 import { NoOpCacheHandler, getCacheHandler, setCacheHandler } from "../shims/cache-handler.js";
 import { headersContextFromRequest, runWithHeadersContext } from "../shims/headers.js";
 import { _consumeRequestScopedCacheLife } from "../shims/cache-request-state.js";
-import { classifyAppRoute, classifyPagesRoute, getAppRouteRenderEntryPath } from "./report.js";
+import { normalizeStaticPathsEntry } from "../routing/route-pattern.js";
 import { BLOCKED_PAGES } from "../shims/constants.js";
+import { buildPregeneratedConcretePathTable } from "../server/prerender-manifest.js";
 import { concatUint8Arrays, decodeRscEmbeddedChunk } from "../server/app-rsc-embedded-chunks.js";
 import { navigationRuntimeRscBootstrapExpression } from "../server/app-ssr-stream.js";
-import { createAppPprFallbackShells, markAppPprDynamicFallbackShellHtml } from "../server/app-ppr-fallback-shell.js";
 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 { startProdServer } from "../server/prod-server.js";
 import fs from "node:fs";
@@ -80,7 +81,7 @@ function extractRscPayloadFromPrerenderedHtml(html) {
 	let match;
 	while ((match = scriptPattern.exec(html)) !== null) {
 		const script = (match[1] ?? "").trim().replace(/;$/, "");
-		if (script === RSC_RUNTIME_DONE_SCRIPT || script === RSC_LEGACY_DONE_SCRIPT) {
+		if (script === RSC_RUNTIME_DONE_SCRIPT || script === RSC_LEGACY_DONE_SCRIPT || script.endsWith(`;${RSC_RUNTIME_DONE_SCRIPT}`)) {
 			sawDone = true;
 			continue;
 		}
@@ -721,10 +722,12 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 				const htmlRender = await runWithHeadersContext(headersContextFromRequest(htmlRequest), async () => {
 					const response = await rscHandler(htmlRequest);
 					const cacheControl = response.headers.get("cache-control") ?? "";
+					const linkHeader = response.headers.get("link");
 					if (!response.ok || isSpeculative && cacheControl.includes("no-store")) {
 						await response.body?.cancel();
 						return {
 							cacheControl,
+							linkHeader,
 							html: null,
 							ok: response.ok,
 							requestCacheLife: null,
@@ -733,6 +736,7 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 					}
 					return {
 						cacheControl,
+						linkHeader,
 						html: await response.text(),
 						ok: true,
 						requestCacheLife: _consumeRequestScopedCacheLife(),
@@ -800,6 +804,7 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 					revalidate: renderedRevalidate,
 					...typeof renderedRevalidate === "number" ? { expire: renderedCacheControl.expire } : {},
 					router: "app",
+					...htmlRender.linkHeader ? { headers: { link: htmlRender.linkHeader } } : {},
 					...urlPath !== routePattern ? { path: urlPath } : {},
 					...isFallback ? { fallback: true } : {}
 				};
@@ -907,6 +912,7 @@ function writePrerenderIndex(routes, outDir, options) {
 			revalidate: r.revalidate,
 			...typeof r.revalidate === "number" ? { expire: r.expire } : {},
 			router: r.router,
+			...r.headers ? { headers: r.headers } : {},
 			...r.path ? { path: r.path } : {},
 			...r.fallback ? { fallback: true } : {}
 		};
@@ -924,7 +930,8 @@ function writePrerenderIndex(routes, outDir, options) {
 	const index = {
 		...buildId ? { buildId } : {},
 		...typeof trailingSlash === "boolean" ? { trailingSlash } : {},
-		routes: indexRoutes
+		routes: indexRoutes,
+		pregeneratedConcretePaths: buildPregeneratedConcretePathTable({ routes: indexRoutes })
 	};
 	fs.writeFileSync(path.join(outDir, "vinext-prerender.json"), JSON.stringify(index, null, 2), "utf-8");
 }

package/dist/build/report.d.ts

@@ -17,6 +17,13 @@ type RouteRow = {
   prerendered?: boolean;
 };
 type AppRouteRenderEntry = Pick<AppRoute, "pagePath" | "routePath" | "parallelSlots">;
+type StaticMiddlewareMatcherObject = {
+  source: string;
+  locale?: false;
+  has?: Array<Record<string, string>>;
+  missing?: Array<Record<string, string>>;
+};
+type StaticMiddlewareMatcher = string | Array<string | StaticMiddlewareMatcherObject>;
 declare function getAppRouteRenderEntryPath(route: AppRouteRenderEntry): string | null;
 /**
  * Returns true if the source code contains an export declaration with the given name.
@@ -28,12 +35,15 @@ declare function getAppRouteRenderEntryPath(route: AppRouteRenderEntry): string
  *   export { foo }
  */
 declare function hasNamedExport(code: string, name: string): boolean;
+/** Returns true when Next.js' analyzer recognizes the requested export name. */
+declare function hasExportedName(code: string, name: string): boolean;
 /**
  * Extracts the string value of `export const <name> = "value"`.
  * Handles TypeScript annotations/assertions and no-substitution template literals.
  * Returns null if the export is absent or not a string literal.
  */
 declare function extractExportConstString(code: string, name: string): string | null;
+declare function extractMiddlewareMatcherConfig(filePath: string): StaticMiddlewareMatcher | undefined;
 /**
  * Extracts the numeric value of `export const <name> = <number|false>`.
  * Supports integers, decimals, negative values, `Infinity`, and `false`.
@@ -121,7 +131,8 @@ declare function formatBuildReport(rows: RouteRow[], routerLabel?: string): stri
  * Scans the project at `root`, classifies all routes, and prints the
  * Next.js-style build report to stdout.
  *
- * Called at the end of `vinext build` in cli.ts.
+ * `root` must be forward-slash — it is passed to `findDir`. The caller (the
+ * `vinext build` entry in cli.ts) normalizes it.
  */
 declare function printBuildReport(options: {
   root: string;
@@ -129,4 +140,4 @@ declare function printBuildReport(options: {
   prerenderResult?: PrerenderResult;
 }): Promise<void>;
 //#endregion
-export { RouteRow, RouteType, buildReportRows, classifyAppRoute, classifyLayoutSegmentConfig, classifyPagesRoute, extractExportConstNumber, extractExportConstString, extractGetStaticPropsRevalidate, formatBuildReport, getAppRouteRenderEntryPath, hasNamedExport, printBuildReport };
+export { RouteRow, RouteType, StaticMiddlewareMatcher, buildReportRows, classifyAppRoute, classifyLayoutSegmentConfig, classifyPagesRoute, extractExportConstNumber, extractExportConstString, extractGetStaticPropsRevalidate, extractMiddlewareMatcherConfig, formatBuildReport, getAppRouteRenderEntryPath, hasExportedName, hasNamedExport, printBuildReport };

package/dist/build/report.js

@@ -22,6 +22,7 @@ import { parseSync } from "vite";
 * `export const revalidate` are classified as "unknown" rather than "static"
 * to avoid false confidence.
 */
+const UNSUPPORTED_STATIC_VALUE = Symbol("unsupported static value");
 function getAppRouteRenderEntryPath(route) {
 	if (route.pagePath) return route.pagePath;
 	if (route.routePath) return null;
@@ -72,6 +73,21 @@ function hasNamedExport(code, name) {
 	if (!program) return false;
 	return hasNamedExportInProgram(program, name);
 }
+/** Returns true when Next.js' analyzer recognizes the requested export name. */
+function hasExportedName(code, name) {
+	const program = parseRouteModule(code);
+	if (!program) return false;
+	for (const node of program.body) {
+		if (node.type !== "ExportNamedDeclaration") continue;
+		if (node.exportKind === "type") continue;
+		if (declarationHasBindingName(node.declaration, name)) return true;
+		for (const specifier of node.specifiers) {
+			if (specifier.exportKind === "type") continue;
+			if (moduleExportNameValue(specifier.local) === name) return true;
+		}
+	}
+	return false;
+}
 function hasNamedExportInProgram(program, name) {
 	for (const node of program.body) {
 		if (node.type !== "ExportNamedDeclaration") continue;
@@ -117,6 +133,86 @@ function extractStringFromConstInitializer(initializer) {
 	if (expression.type === "TemplateLiteral" && expression.expressions.length === 0) return expression.quasis[0]?.value.cooked ?? expression.quasis[0]?.value.raw ?? null;
 	return null;
 }
+function extractMiddlewareMatcherConfig(filePath) {
+	let code;
+	try {
+		code = fs.readFileSync(filePath, "utf8");
+	} catch {
+		return;
+	}
+	const initializer = findExportedConstInitializer(code, "config");
+	if (!initializer) return void 0;
+	const config = unwrapStaticExpression(initializer);
+	if (config.type !== "ObjectExpression") return void 0;
+	const matcherExpression = objectPropertyValue(config, "matcher");
+	if (!matcherExpression) return void 0;
+	const value = extractStaticJsonValue(matcherExpression);
+	return isStaticMiddlewareMatcher(value) ? value : void 0;
+}
+function objectPropertyValue(object, key) {
+	for (const property of object.properties) {
+		if (property.type !== "Property" || property.computed) continue;
+		if (propertyKeyName(property.key) !== key) continue;
+		return property.value;
+	}
+	return null;
+}
+function propertyKeyName(key) {
+	if (key.type === "Identifier") return key.name;
+	if (key.type === "Literal" && typeof key.value === "string") return key.value;
+	return null;
+}
+function extractStaticJsonValue(expression) {
+	const value = unwrapStaticExpression(expression);
+	if (value.type === "Literal") {
+		if (typeof value.value === "string" || typeof value.value === "number" || typeof value.value === "boolean" || value.value === null) return value.value;
+		return UNSUPPORTED_STATIC_VALUE;
+	}
+	if (value.type === "TemplateLiteral" && value.expressions.length === 0) return value.quasis[0]?.value.cooked ?? value.quasis[0]?.value.raw ?? "";
+	if (value.type === "ArrayExpression") {
+		const items = [];
+		for (const element of value.elements) {
+			if (!element || element.type === "SpreadElement") return UNSUPPORTED_STATIC_VALUE;
+			const item = extractStaticJsonValue(element);
+			if (item === UNSUPPORTED_STATIC_VALUE) return UNSUPPORTED_STATIC_VALUE;
+			items.push(item);
+		}
+		return items;
+	}
+	if (value.type === "ObjectExpression") {
+		const object = {};
+		for (const property of value.properties) {
+			if (property.type !== "Property" || property.computed) return UNSUPPORTED_STATIC_VALUE;
+			const key = propertyKeyName(property.key);
+			if (!key) return UNSUPPORTED_STATIC_VALUE;
+			const propertyValue = extractStaticJsonValue(property.value);
+			if (propertyValue === UNSUPPORTED_STATIC_VALUE) return UNSUPPORTED_STATIC_VALUE;
+			object[key] = propertyValue;
+		}
+		return object;
+	}
+	return UNSUPPORTED_STATIC_VALUE;
+}
+function isStaticMiddlewareMatcher(value) {
+	if (typeof value === "string") return true;
+	if (!Array.isArray(value)) return false;
+	return value.every((item) => typeof item === "string" || isStaticMiddlewareMatcherObject(item));
+}
+function isStaticMiddlewareMatcherObject(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const record = value;
+	if (typeof record.source !== "string") return false;
+	if (record.locale !== void 0 && record.locale !== false) return false;
+	return isStaticMatcherConditions(record.has) && isStaticMatcherConditions(record.missing);
+}
+function isStaticMatcherConditions(value) {
+	if (value === void 0) return true;
+	if (!Array.isArray(value)) return false;
+	return value.every((item) => {
+		if (!item || typeof item !== "object" || Array.isArray(item)) return false;
+		return Object.values(item).every((entry) => typeof entry === "string");
+	});
+}
 /**
 * Extracts the numeric value of `export const <name> = <number|false>`.
 * Supports integers, decimals, negative values, `Infinity`, and `false`.
@@ -474,7 +570,8 @@ function formatBuildReport(rows, routerLabel = "app") {
 * Scans the project at `root`, classifies all routes, and prints the
 * Next.js-style build report to stdout.
 *
-* Called at the end of `vinext build` in cli.ts.
+* `root` must be forward-slash — it is passed to `findDir`. The caller (the
+* `vinext build` entry in cli.ts) normalizes it.
 */
 async function printBuildReport(options) {
 	const { root } = options;
@@ -501,4 +598,4 @@ async function printBuildReport(options) {
 	}
 }
 //#endregion
-export { buildReportRows, classifyAppRoute, classifyLayoutSegmentConfig, classifyPagesRoute, extractExportConstNumber, extractExportConstString, extractGetStaticPropsRevalidate, formatBuildReport, getAppRouteRenderEntryPath, hasNamedExport, printBuildReport };
+export { buildReportRows, classifyAppRoute, classifyLayoutSegmentConfig, classifyPagesRoute, extractExportConstNumber, extractExportConstString, extractGetStaticPropsRevalidate, extractMiddlewareMatcherConfig, formatBuildReport, getAppRouteRenderEntryPath, hasExportedName, hasNamedExport, printBuildReport };

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

@@ -56,6 +56,13 @@ type RunPrerenderOptions = {
  * `output: 'export'`. Exported for direct unit testing. Refs cloudflare/vinext#1982
  */
 declare function assertNoFatalPrerenderRoutes(routes: readonly PrerenderRouteResult[]): void;
+/**
+ * Statically generate routes and return the prerender result.
+ *
+ * `options.root` must be forward-slash — it is passed to `findDir` and flows
+ * into the route model. The caller (the `vinext build` entry in cli.ts)
+ * normalizes it.
+ */
 declare function runPrerender(options: RunPrerenderOptions): Promise<PrerenderResult | null>;
 //#endregion
 export { assertNoFatalPrerenderRoutes, runPrerender };

package/dist/build/run-prerender.js

@@ -6,12 +6,13 @@ import { loadNextConfig, resolveNextConfig } from "../config/next-config.js";
 import { readPrerenderSecret } from "./server-manifest.js";
 import { startProdServer } from "../server/prod-server.js";
 import { prerenderApp, prerenderPages, writePrerenderIndex } from "./prerender.js";
+import { injectPregeneratedConcretePaths } from "./inject-pregenerated-paths.js";
 import fs from "node:fs";
 import path from "node:path";
 //#region src/build/run-prerender.ts
 /**
 * Shared prerender runner used by both `vinext build` (cli.ts) and
-* `vinext deploy --prerender-all` (deploy.ts).
+* `vinext-cloudflare deploy --prerender-all` (deploy.ts).
 *
 * `runPrerender` handles route scanning, dynamic imports, progress reporting,
 * and result summarisation.
@@ -95,6 +96,13 @@ function assertNoFatalPrerenderRoutes(routes) {
 	const fatalList = fatalRoutes.map((r) => `  ${r.route}: ${r.error}`).join("\n");
 	throw new Error(`Prerender failed: ${fatalRoutes.length} route${fatalRoutes.length !== 1 ? "s" : ""} errored during static generation.\n${fatalList}`);
 }
+/**
+* Statically generate routes and return the prerender result.
+*
+* `options.root` must be forward-slash — it is passed to `findDir` and flows
+* into the route model. The caller (the `vinext build` entry in cli.ts)
+* normalizes it.
+*/
 async function runPrerender(options) {
 	const { root } = options;
 	const appDir = findDir(root, "app", "src/app");
@@ -215,6 +223,7 @@ async function runPrerender(options) {
 		const errorRoutes = allRoutes.filter((r) => r.status === "error").map((r) => `  ${r.route}: ${r.error}`).join("\n");
 		throw new Error(`Static export failed: ${errors} route${errors !== 1 ? "s" : ""} cannot be statically exported.\n${errorRoutes}\n\nRemove server-side data fetching (getServerSideProps, force-dynamic, revalidate) from these routes, or remove \`output: "export"\` from next.config.js.`);
 	}
+	injectPregeneratedConcretePaths(root);
 	return {
 		routes: allRoutes,
 		...allOutputFiles.length > 0 ? { outputFiles: allOutputFiles } : {}

package/dist/build/standalone.js

@@ -167,6 +167,8 @@ function emitStandaloneOutput(options) {
 		dereference: true,
 		filter: (src) => !path.relative(serverDir, src).split(path.sep).includes("node_modules")
 	});
+	const clientAssetsSidecar = path.join(outDir, "vinext-client-assets.js");
+	if (fs.existsSync(clientAssetsSidecar)) fs.copyFileSync(clientAssetsSidecar, path.join(standaloneDistDir, "vinext-client-assets.js"));
 	const publicDir = path.join(root, "public");
 	if (fs.existsSync(publicDir)) fs.cpSync(publicDir, path.join(standaloneDir, "public"), {
 		recursive: true,

package/dist/cache/cache-adapters-virtual.js

@@ -35,9 +35,9 @@ function generateCacheAdaptersModule(cache) {
 		lines.push(`import __vinextCdnAdapterFactory from ${JSON.stringify(cdn.adapter)};`);
 		lines.push(`import { setCdnCacheAdapter } from "vinext/shims/cdn-cache";`);
 	}
-	lines.push("", "// A factory that throws (e.g. a missing binding on an incompatible runtime)", "// is logged and skipped so the default handler stays in place.", "let __vinextCacheAdaptersRegistered = false;", "", "export function registerConfiguredCacheAdapters(env) {", "  if (__vinextCacheAdaptersRegistered) return;", "  __vinextCacheAdaptersRegistered = true;");
-	if (data?.adapter) lines.push("  try {", `    setDataCacheHandler(__vinextDataAdapterFactory({ env, options: ${inlineOptions(data.adapter, data.options)} }));`, "  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured data cache adapter; using the default handler.\", error);", "  }");
-	if (cdn?.adapter) lines.push("  try {", `    setCdnCacheAdapter(__vinextCdnAdapterFactory({ env, options: ${inlineOptions(cdn.adapter, cdn.options)} }));`, "  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured CDN cache adapter; using the default adapter.\", error);", "  }");
+	lines.push("", "// A factory that throws (e.g. a missing binding on an incompatible runtime)", "// is logged and skipped so the default handler stays in place.", "function __vinextFormatAdapterError(error) {", "  if (error instanceof Error && error.message) return error.message;", "  try {", "    return String(error);", "  } catch {", "    return '<unknown error>';", "  }", "}", "", "let __vinextCacheAdaptersRegistered = false;", "", "export function registerConfiguredCacheAdapters(env) {", "  if (__vinextCacheAdaptersRegistered) return;", "  __vinextCacheAdaptersRegistered = true;");
+	if (data?.adapter) lines.push("  try {", `    setDataCacheHandler(__vinextDataAdapterFactory({ env, options: ${inlineOptions(data.adapter, data.options)} }));`, "  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured data cache adapter; using the default handler.\\n\" + __vinextFormatAdapterError(error));", "  }");
+	if (cdn?.adapter) lines.push("  try {", `    setCdnCacheAdapter(__vinextCdnAdapterFactory({ env, options: ${inlineOptions(cdn.adapter, cdn.options)} }));`, "  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured CDN cache adapter; using the default adapter.\\n\" + __vinextFormatAdapterError(error));", "  }");
 	lines.push("}", "");
 	return lines.join("\n");
 }