vinext 0.1.8 → 0.2.1

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/css-url-assets.d.ts

@@ -13,6 +13,8 @@ type EmitRestoredCssUrlAsset = (asset: {
  * safe to run on every build-environment stylesheet, vendored CSS included.
  */
 declare function markCssUrlAssetReferences(code: string, id: string): string | null;
+/** Rebase relative asset URLs when Sass inlines a partial into an entry file. */
+declare function rebaseCssUrlAssetReferences(code: string, sourceDirectory: string, targetDirectory: string): string | null;
 /**
  * Mutates emitted CSS assets in place so byte-identical `url()` dependencies
  * keep their distinct Next-compatible filenames. Sibling files are produced via
@@ -26,4 +28,4 @@ declare function markCssUrlAssetReferences(code: string, id: string): string | n
  */
 declare function restoreDedupedCssAssetReferences(bundle: CssUrlAssetBundle, emitRestoredAsset: EmitRestoredCssUrlAsset): void;
 //#endregion
-export { markCssUrlAssetReferences, restoreDedupedCssAssetReferences };
+export { markCssUrlAssetReferences, rebaseCssUrlAssetReferences, restoreDedupedCssAssetReferences };

package/dist/build/css-url-assets.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 //#region src/build/css-url-assets.ts
 /**
 * Next-parity for CSS `url()` asset dependencies.
@@ -128,6 +129,22 @@ function markCssUrlAssetReferences(code, id) {
 		});
 	});
 }
+/** Rebase relative asset URLs when Sass inlines a partial into an entry file. */
+function rebaseCssUrlAssetReferences(code, sourceDirectory, targetDirectory) {
+	return rewriteCssUrls(code, (rawUrl) => {
+		const parts = splitUrl(rawUrl.trim());
+		if (!isRelativeAssetUrl(parts.path)) return null;
+		const lower = parts.path.toLowerCase();
+		if (!CSS_ASSET_EXT_RE.test(lower) || lower.endsWith(".css")) return null;
+		const absolutePath = path.resolve(sourceDirectory, parts.path);
+		let rebasedPath = path.relative(targetDirectory, absolutePath).replaceAll("\\", "/");
+		if (!rebasedPath.startsWith(".")) rebasedPath = `./${rebasedPath}`;
+		return joinUrl({
+			...parts,
+			path: rebasedPath
+		});
+	});
+}
 function isCssFileName(fileName) {
 	return fileName.toLowerCase().endsWith(".css");
 }
@@ -210,4 +227,4 @@ function stripChunkMarkers(code) {
 	return code.replace(CSS_URL_MARKER_PARAM_RE, (_m, leadingQuestion) => leadingQuestion ? leadingQuestion : "");
 }
 //#endregion
-export { markCssUrlAssetReferences, restoreDedupedCssAssetReferences };
+export { markCssUrlAssetReferences, rebaseCssUrlAssetReferences, restoreDedupedCssAssetReferences };

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

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

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

@@ -0,0 +1,21 @@
+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) {
+		globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = table;
+		code = `${VINEXT_PREGEN_START}\nglobalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = ${JSON.stringify(table)};\n${VINEXT_PREGEN_END}\n` + code;
+	} else delete globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS;
+	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-server-entry.d.ts

@@ -0,0 +1 @@
+export { };

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

@@ -0,0 +1,49 @@
+import { NoOpCacheHandler, setCacheHandler } from "../shims/cache-handler.js";
+import { startProdServer } from "../server/prod-server.js";
+//#region src/build/prerender-server-entry.ts
+/**
+* Child-process entry for a parallel prerender render server.
+*
+* Forked by `prerender-server-pool.ts`. React SSR/RSC rendering is CPU-bound
+* JS, so a single-process promise pool serializes every render on one core.
+* This entry lets the prerender phase fan rendering out across N OS processes
+* (one per core, like Next.js's static worker pool): each child starts a normal
+* 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).
+*/
+async function main() {
+	const outDir = process.env.VINEXT_PRERENDER_OUTDIR;
+	if (!outDir) throw new Error("[vinext] prerender server worker: VINEXT_PRERENDER_OUTDIR not set");
+	setCacheHandler(new NoOpCacheHandler());
+	const { port } = await startProdServer({
+		port: 0,
+		host: "127.0.0.1",
+		outDir,
+		noCompression: true,
+		purpose: "prerender",
+		silent: true
+	});
+	if (typeof process.send === "function") process.send({
+		type: "ready",
+		port
+	});
+	else throw new Error("[vinext] prerender server worker: no IPC channel to parent");
+}
+process.on("disconnect", () => process.exit(0));
+main().catch((err) => {
+	const message = err instanceof Error ? err.stack ?? err.message : String(err);
+	if (typeof process.send === "function") {
+		process.send({
+			type: "error",
+			error: message
+		}, () => process.exit(1));
+		return;
+	}
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/build/prerender-server-pool.d.ts

@@ -0,0 +1,44 @@
+//#region src/build/prerender-server-pool.d.ts
+/**
+ * Whether the forkable worker entry exists as a runnable `.js` sibling. False
+ * when vinext runs from source (e.g. the test suite transpiles `.ts` on the
+ * fly and a forked plain-node child can't load `.ts`); callers fall back to the
+ * single in-process server. True in the published/built package.
+ */
+declare function prerenderPoolAvailable(): boolean;
+type PrerenderServerPool = {
+  /** Ports of the forked render servers, for round-robin per-route fetches. */ports: number[];
+  /**
+   * Throw if any worker exited unexpectedly (i.e. not via `close()`). The
+   * caller MUST call this after the render loop: a crashed worker makes every
+   * route routed to it fail with a connection error, which the per-route
+   * handler records as a (non-fatal) error — without this check the build
+   * would emit partial output and still exit 0. Mirrors the single-process
+   * design, where a server crash takes the whole build down loudly.
+   */
+  assertHealthy: () => void;
+  /**
+   * Record a failed fetch to a render worker. This closes the tiny ordering gap
+   * where the request can fail before Node has delivered the child `exit` event.
+   */
+  recordRenderError: (err: unknown) => void; /** Kill every forked server. Safe to call more than once. */
+  close: () => Promise<void>;
+};
+/**
+ * Choose how many render processes to fork for `routeCount` routes.
+ *
+ * Returns 1 to mean "don't fork — render in-process as before" (small apps,
+ * single/dual-core, low memory, or an explicit `--prerender-concurrency 1`).
+ * `maxOverride` comes from `--prerender-concurrency`, which caps both the
+ * number of in-flight route fetches and the worker count (the default is capped
+ * at `min(cores, 8)`).
+ */
+declare function resolvePrerenderPoolSize(routeCount: number, maxOverride?: number): number;
+/**
+ * Fork `size` production servers against `outDir` and resolve once all are
+ * listening. Each child reports its port over IPC. Rejects (and tears down any
+ * already-started children) if any child fails to come up.
+ */
+declare function startPrerenderServerPool(outDir: string, size: number, entry?: string): Promise<PrerenderServerPool>;
+//#endregion
+export { PrerenderServerPool, prerenderPoolAvailable, resolvePrerenderPoolSize, startPrerenderServerPool };

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

@@ -0,0 +1,194 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+import { fork } from "node:child_process";
+//#region src/build/prerender-server-pool.ts
+/**
+* Parallel prerender server pool.
+*
+* React SSR/RSC rendering during prerender is CPU-bound JS. vinext renders
+* every route by fetching it from a single in-process production server, so the
+* promise pool in `prerender.ts` only overlaps I/O — the actual rendering
+* serializes on one core. This module forks a pool of OS processes (one vinext
+* production server each, on its own ephemeral port) so the prerender phase can
+* spread rendering across cores, mirroring Next.js's static worker pool. The
+* caller load-balances per-route fetches across `ports`.
+*
+* child_process (not worker_threads) is deliberate: worker threads share the
+* process and contend badly for CPU on this workload (measured ~2× slower
+* per route and non-scaling), which is also why Next.js uses processes.
+*/
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKER_ENTRY = path.join(__dirname, "prerender-server-entry.js");
+/**
+* Whether the forkable worker entry exists as a runnable `.js` sibling. False
+* when vinext runs from source (e.g. the test suite transpiles `.ts` on the
+* fly and a forked plain-node child can't load `.ts`); callers fall back to the
+* single in-process server. True in the published/built package.
+*/
+function prerenderPoolAvailable() {
+	return fs.existsSync(WORKER_ENTRY);
+}
+/** Hard cap on render processes. Beyond this the main thread (which collects
+* HTML and writes files) becomes the bottleneck, so more workers don't help. */
+const MAX_POOL_SIZE = 8;
+/** Don't fork a dedicated process unless a worker gets at least this many
+* routes — below this the fork + bundle-import startup cost outweighs the
+* parallel-render saving (measured: a 2-worker pool only reliably beats the
+* single server from ~50 routes/worker up). */
+const MIN_ROUTES_PER_WORKER = 48;
+/** Rough memory budget reserved for the main build process plus its in-process
+* prerender server. */
+const APPROX_MAIN_PROCESS_BYTES = 768 * 1024 * 1024;
+/** Rough memory budget per worker (a worker loads the whole server bundle).
+* Used with total system memory as a coarse upper bound on constrained machines
+* so K render processes don't OOM. Deliberately under-forks rather than risking
+* OOM; measured mid-size apps are usually lower (~260-380 MB/worker). */
+const APPROX_BYTES_PER_WORKER = 768 * 1024 * 1024;
+/** Per-worker readiness timeout. */
+const WORKER_READY_TIMEOUT_MS = 6e4;
+/** Best-effort close timeout so build cleanup is not blocked forever by a wedged child. */
+const WORKER_CLOSE_TIMEOUT_MS = 5e3;
+const PRERENDER_WORKER_TRANSPORT_ERROR_CODES = new Set([
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"EPIPE",
+	"UND_ERR_SOCKET"
+]);
+/**
+* Choose how many render processes to fork for `routeCount` routes.
+*
+* Returns 1 to mean "don't fork — render in-process as before" (small apps,
+* single/dual-core, low memory, or an explicit `--prerender-concurrency 1`).
+* `maxOverride` comes from `--prerender-concurrency`, which caps both the
+* number of in-flight route fetches and the worker count (the default is capped
+* at `min(cores, 8)`).
+*/
+function resolvePrerenderPoolSize(routeCount, maxOverride) {
+	const cores = Math.max(1, os.availableParallelism());
+	const byCores = Math.max(1, Math.min(cores - 1, MAX_POOL_SIZE));
+	const memoryForWorkers = Math.max(0, os.totalmem() - APPROX_MAIN_PROCESS_BYTES);
+	const byMemory = Math.max(1, Math.floor(memoryForWorkers / APPROX_BYTES_PER_WORKER));
+	const cap = maxOverride && maxOverride > 0 ? Math.min(maxOverride, byCores) : byCores;
+	const byRoutes = Math.floor(routeCount / MIN_ROUTES_PER_WORKER);
+	return Math.max(1, Math.min(cap, byMemory, byRoutes));
+}
+function getErrorCauseCode(err) {
+	if (!(err instanceof Error)) return void 0;
+	const cause = err.cause;
+	return typeof cause?.code === "string" ? cause.code : void 0;
+}
+function isWorkerTransportError(err) {
+	const code = getErrorCauseCode(err);
+	if (code && PRERENDER_WORKER_TRANSPORT_ERROR_CODES.has(code)) return true;
+	return err instanceof TypeError && err.message === "fetch failed";
+}
+/**
+* Fork `size` production servers against `outDir` and resolve once all are
+* listening. Each child reports its port over IPC. Rejects (and tears down any
+* already-started children) if any child fails to come up.
+*/
+async function startPrerenderServerPool(outDir, size, entry = WORKER_ENTRY) {
+	const children = [];
+	let shuttingDown = false;
+	let crash = null;
+	let renderTransportError = null;
+	const close = async () => {
+		shuttingDown = true;
+		await Promise.all(children.map(closeChild));
+	};
+	try {
+		const readies = Array.from({ length: size }, () => {
+			const child = fork(entry, [], {
+				cwd: process.cwd(),
+				env: {
+					...process.env,
+					VINEXT_PRERENDER: "1",
+					VINEXT_PRERENDER_OUTDIR: outDir
+				},
+				stdio: [
+					"ignore",
+					"inherit",
+					"inherit",
+					"ipc"
+				]
+			});
+			children.push(child);
+			return new Promise((resolve, reject) => {
+				const timer = setTimeout(() => {
+					reject(/* @__PURE__ */ new Error("[vinext] prerender render server did not start within 60s"));
+				}, WORKER_READY_TIMEOUT_MS);
+				const cleanupStartupListeners = () => {
+					clearTimeout(timer);
+					child.off("message", onMessage);
+					child.off("error", onError);
+					child.off("exit", onStartupExit);
+				};
+				const onMessage = (msg) => {
+					cleanupStartupListeners();
+					if (msg?.type === "ready" && typeof msg.port === "number") {
+						child.once("exit", (code, signal) => {
+							if (!shuttingDown && !crash) crash = {
+								port: msg.port,
+								code,
+								signal
+							};
+						});
+						resolve(msg.port);
+					} else reject(/* @__PURE__ */ new Error(`[vinext] prerender render server failed: ${msg?.error ?? "unknown"}`));
+				};
+				const onError = (err) => {
+					cleanupStartupListeners();
+					reject(err);
+				};
+				const onStartupExit = (code, signal) => {
+					if (code !== null || signal !== null) {
+						cleanupStartupListeners();
+						reject(/* @__PURE__ */ new Error(`[vinext] prerender render server exited during startup (code ${code}, signal ${signal})`));
+					}
+				};
+				child.once("message", onMessage);
+				child.once("error", onError);
+				child.once("exit", onStartupExit);
+			});
+		});
+		const ports = await Promise.all(readies);
+		const recordRenderError = (err) => {
+			if (!renderTransportError && isWorkerTransportError(err)) renderTransportError = err instanceof Error ? err : new Error(String(err));
+		};
+		const assertHealthy = () => {
+			if (crash) throw new Error(`[vinext] A prerender render worker (port ${crash.port}) exited unexpectedly (code ${crash.code}, signal ${crash.signal}) during the build. Prerender output is incomplete; failing the build. This is often an out-of-memory kill — try a lower --prerender-concurrency.`);
+			if (renderTransportError) {
+				const causeCode = getErrorCauseCode(renderTransportError);
+				throw new Error(`[vinext] A prerender render worker request failed` + (causeCode ? ` (${causeCode})` : "") + " before the worker exit was observed. Prerender output is incomplete; failing the build. This is often an out-of-memory kill — try a lower --prerender-concurrency.");
+			}
+		};
+		return {
+			ports,
+			assertHealthy,
+			recordRenderError,
+			close
+		};
+	} catch (err) {
+		await close();
+		throw err;
+	}
+}
+async function closeChild(child) {
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	const exited = new Promise((resolve) => {
+		const timer = setTimeout(resolve, WORKER_CLOSE_TIMEOUT_MS);
+		timer.unref?.();
+		const finish = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		child.once("exit", finish);
+		if (child.exitCode !== null || child.signalCode !== null) finish();
+	});
+	if (!child.killed) child.kill("SIGKILL");
+	await exited;
+}
+//#endregion
+export { prerenderPoolAvailable, resolvePrerenderPoolSize, startPrerenderServerPool };

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;