@vinext/cloudflare 0.2.1 → 1.0.0-beta.1

package/dist/deploy.js

@@ -1,16 +1,23 @@
-import { runTPR } from "./tpr.js";
-import { formatImageOptimizationHint, formatMissingCacheAdapterError, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler } from "./deploy-config.js";
+import { readPrerenderWarmPaths, warmCdnCache } from "./cdn-warm.js";
+import { parseWranglerConfig, runTPR } from "./tpr.js";
+import { formatImageOptimizationHint, formatMissingCacheAdapterError, resolveKvDataAdapterConfig, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler } from "./deploy-config.js";
+import { parseWorkersDevUrl } from "./workers-dev-url.js";
+import { runWranglerDeploymentStatus, runWranglerTriggersDeploy, runWranglerVersionDeploy, runWranglerVersionUpload } from "./version-deploy.js";
+import { buildPrerenderKVPairs } from "./prerender-kv-populate.js";
 import { createRequire } from "node:module";
-import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import { emitPrerenderPathManifest } from "vinext/internal/build/prerender-paths";
+import os from "node:os";
+import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import { pathToFileURL } from "node:url";
 import { runPrerender } from "vinext/internal/build/run-prerender";
 import { loadDotenv } from "vinext/internal/config/dotenv";
-import { loadNextConfig, resolveNextConfig } from "vinext/internal/config/next-config";
-import { formatVinextPrerenderLabel, loadVinextPrerenderConfigFromViteConfig, resolveVinextPrerenderDecision } from "vinext/internal/config/prerender";
+import { findVinextNextConfigInPlugins, loadNextConfig, resolveNextConfig, resolveNextConfigInput } from "vinext/internal/config/next-config";
+import { findVinextCacheConfigInPlugins, findVinextPrerenderConfigInPlugins, findVinextRouteRootConfigInPlugins, formatVinextPrerenderLabel, resolveVinextPrerenderDecision } from "vinext/internal/config/prerender";
 import { detectProject, findInNodeModules, formatMissingCloudflarePluginError, getMissingDeps } from "vinext/internal/utils/project";
+import { PHASE_PRODUCTION_BUILD } from "vinext/shims/constants";
 //#region src/deploy.ts
 /**
 * vinext-cloudflare deploy — one-command Cloudflare Workers deployment.
@@ -27,6 +34,16 @@ function parsePositiveIntegerArg(raw, flag) {
 	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} expects a positive integer, but got "${raw}".`);
 	return parsed;
 }
+function parseNonNegativeIntegerArg(raw, flag) {
+	if (raw === "") throw new Error(`${flag} requires a value, but none was provided.`);
+	const parsed = Number(raw);
+	if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${flag} expects a non-negative integer, but got "${raw}".`);
+	return parsed;
+}
+function formatUnknownError(error) {
+	if (error instanceof Error && error.message) return error.message;
+	return String(error);
+}
 /** Deploy command flag definitions for util.parseArgs. */
 const deployArgOptions = {
 	help: {
@@ -40,6 +57,7 @@ const deployArgOptions = {
 	},
 	env: { type: "string" },
 	name: { type: "string" },
+	config: { type: "string" },
 	"skip-build": {
 		type: "boolean",
 		default: false
@@ -53,6 +71,21 @@ const deployArgOptions = {
 		default: false
 	},
 	"prerender-concurrency": { type: "string" },
+	"experimental-warm-cdn-cache": {
+		type: "boolean",
+		default: false
+	},
+	"warm-cdn-concurrency": { type: "string" },
+	"warm-cdn-timeout": { type: "string" },
+	"warm-cdn-retries": { type: "string" },
+	"warm-cdn-strict": {
+		type: "boolean",
+		default: false
+	},
+	"warm-cdn-include-fallbacks": {
+		type: "boolean",
+		default: false
+	},
 	"experimental-tpr": {
 		type: "boolean",
 		default: false
@@ -81,10 +114,17 @@ function parseDeployArgs(args) {
 		preview: values.preview,
 		env: values.env?.trim() || void 0,
 		name: values.name?.trim() || void 0,
+		config: values.config?.trim() || void 0,
 		skipBuild: values["skip-build"],
 		dryRun: values["dry-run"],
 		prerenderAll: values["prerender-all"],
 		prerenderConcurrency: values["prerender-concurrency"] === void 0 ? void 0 : parsePositiveIntegerArg(values["prerender-concurrency"], "--prerender-concurrency"),
+		warmCdnCache: values["experimental-warm-cdn-cache"],
+		warmCdnConcurrency: values["warm-cdn-concurrency"] === void 0 ? void 0 : parsePositiveIntegerArg(values["warm-cdn-concurrency"], "--warm-cdn-concurrency"),
+		warmCdnTimeout: values["warm-cdn-timeout"] === void 0 ? void 0 : parsePositiveIntegerArg(values["warm-cdn-timeout"], "--warm-cdn-timeout"),
+		warmCdnRetries: values["warm-cdn-retries"] === void 0 ? void 0 : parseNonNegativeIntegerArg(values["warm-cdn-retries"], "--warm-cdn-retries"),
+		warmCdnStrict: values["warm-cdn-strict"],
+		warmCdnIncludeFallbacks: values["warm-cdn-include-fallbacks"],
 		experimentalTPR: values["experimental-tpr"],
 		tprCoverage: parseIntArg("tpr-coverage", values["tpr-coverage"]),
 		tprLimit: parseIntArg("tpr-limit", values["tpr-limit"]),
@@ -124,6 +164,18 @@ async function loadProjectViteApi(root) {
 	}
 	return await (vitePath === "vite" ? import(vitePath) : import(pathToFileURL(vitePath).href));
 }
+async function loadDeployViteConfigMetadata(root) {
+	const plugins = (await (await loadProjectViteApi(root)).loadConfigFromFile({
+		command: "build",
+		mode: "production"
+	}, void 0, root))?.config.plugins;
+	return {
+		cacheConfig: viteConfigHasCacheAdapter(root) ? await findVinextCacheConfigInPlugins(plugins) : null,
+		nextConfig: await findVinextNextConfigInPlugins(plugins),
+		prerenderConfig: await findVinextPrerenderConfigInPlugins(plugins),
+		routeRootConfig: await findVinextRouteRootConfigInPlugins(plugins)
+	};
+}
 async function runBuild(info, env) {
 	console.log("\n  Building for Cloudflare Workers...\n");
 	const { createBuilder } = await loadProjectViteApi(info.root);
@@ -131,6 +183,25 @@ async function runBuild(info, env) {
 		await (await createBuilder({ root: info.root })).buildApp();
 	});
 }
+async function populateKVCacheFromPrerenderedArtifacts(root, wranglerEnv, cacheConfig) {
+	const kvConfig = resolveKvDataAdapterConfig(cacheConfig);
+	if (!kvConfig) return;
+	const { routeCount, pairs } = buildPrerenderKVPairs(path.join(root, "dist", "server"), {
+		appPrefix: kvConfig.appPrefix,
+		ttlSeconds: kvConfig.ttlSeconds
+	});
+	if (pairs.length === 0) {
+		console.log("  KV cache: Skipping prerender upload (no App Router prerendered cache entries found).");
+		return;
+	}
+	await runWranglerKVBulkPut(root, {
+		binding: kvConfig.binding,
+		env: wranglerEnv,
+		pairs
+	});
+	console.log(`  KV cache: Uploaded ${pairs.length} entr${pairs.length === 1 ? "y" : "ies"} for ${routeCount} prerendered route${routeCount === 1 ? "" : "s"}.`);
+}
+const KV_BULK_PUT_CHUNK_SIZE = 25;
 function validateWranglerEnvName(env) {
 	if (env.includes("\0")) throw new Error("Wrangler environment names cannot contain null bytes.");
 	return env;
@@ -138,6 +209,25 @@ function validateWranglerEnvName(env) {
 function buildWranglerDeployArgs(options) {
 	const args = ["deploy"];
 	const env = options.env || (options.preview ? "preview" : void 0);
+	if (options.config) args.push("--config", options.config);
+	if (options.name) args.push("--name", options.name);
+	if (env) args.push("--env", validateWranglerEnvName(env));
+	return {
+		args,
+		env
+	};
+}
+function buildWranglerKVBulkPutArgs(options) {
+	const env = options.env || void 0;
+	const args = [
+		"kv",
+		"bulk",
+		"put",
+		options.filePath,
+		"--binding",
+		options.binding,
+		"--remote"
+	];
 	if (env) args.push("--env", validateWranglerEnvName(env));
 	return {
 		args,
@@ -179,21 +269,196 @@ function buildWranglerInvocation(root, options, nodeExecutable = process.execPat
 		env
 	};
 }
-function runWranglerDeploy(root, options, execute = execFileSync) {
-	const execOpts = {
+async function runWranglerKVBulkPut(root, options, execute = spawn, nodeExecutable = process.execPath) {
+	const tempDir = fs.mkdtempSync(path.join(options.tempDir ?? os.tmpdir(), "vinext-kv-bulk-"));
+	try {
+		const wranglerBin = resolveWranglerBin(root);
+		const totalChunks = Math.ceil(options.pairs.length / KV_BULK_PUT_CHUNK_SIZE);
+		for (let i = 0; i < totalChunks; i++) {
+			const filePath = path.join(tempDir, `prerender-kv-${i}.json`);
+			const chunk = options.pairs.slice(i * KV_BULK_PUT_CHUNK_SIZE, (i + 1) * KV_BULK_PUT_CHUNK_SIZE);
+			fs.writeFileSync(filePath, JSON.stringify(chunk), "utf-8");
+			const { args } = buildWranglerKVBulkPutArgs({
+				binding: options.binding,
+				env: options.env,
+				filePath
+			});
+			const invocation = buildNodeCliInvocation(wranglerBin, args, nodeExecutable);
+			const child = execute(invocation.file, invocation.args, {
+				cwd: root,
+				stdio: "inherit",
+				shell: false
+			});
+			await new Promise((resolve, reject) => {
+				child.once("error", reject);
+				child.once("close", (code, signal) => {
+					if (code === 0) {
+						resolve();
+						return;
+					}
+					const exitReason = signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`;
+					reject(/* @__PURE__ */ new Error(`Wrangler KV bulk put failed with ${exitReason}.`));
+				});
+			});
+		}
+	} finally {
+		fs.rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function runWranglerDeploy(root, options, execute = spawn) {
+	const spawnOptions = {
 		cwd: root,
-		stdio: "pipe",
-		encoding: "utf-8",
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		],
 		shell: false
 	};
 	const { file, args, env } = buildWranglerInvocation(root, options);
 	if (env) console.log(`\n  Deploying to env: ${env}...`);
 	else console.log("\n  Deploying to production...");
-	const output = execute(file, args, execOpts);
-	const urlMatch = output.match(/https:\/\/[^\s]+\.workers\.dev[^\s]*/);
-	const deployedUrl = urlMatch ? urlMatch[0] : null;
-	if (output.trim()) for (const line of output.trim().split("\n")) console.log(`  ${line}`);
-	return deployedUrl ?? "(URL not detected in wrangler output)";
+	const child = execute(file, args, spawnOptions);
+	let output = "";
+	child.stdout?.on("data", (chunk) => {
+		const text = chunk.toString();
+		output += text;
+		process.stdout.write(text);
+	});
+	child.stderr?.on("data", (chunk) => {
+		const text = chunk.toString();
+		output += text;
+		process.stderr.write(text);
+	});
+	await new Promise((resolve, reject) => {
+		child.once("error", reject);
+		child.once("close", (code, signal) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			const exitReason = signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`;
+			reject(/* @__PURE__ */ new Error(`Wrangler deploy failed with ${exitReason}.`));
+		});
+	});
+	return parseWorkersDevUrl(output) ?? "(URL not detected in wrangler output)";
+}
+async function deployWithCdnWarmup(root, paths, options) {
+	const upload = runWranglerVersionUpload(root, options);
+	const wranglerConfig = parseWranglerConfig(root, options.config);
+	const stagingTraffic = getZeroPercentStagingTraffic(readWranglerDeploymentStatus(root, options), upload.versionId);
+	let staged = null;
+	let triggersDeployedUrl = null;
+	let warmedBeforePromotion = false;
+	let triggersApplied = false;
+	function applyTriggers() {
+		if (triggersApplied) return;
+		triggersDeployedUrl = runWranglerTriggersDeploy(root, options).deployedUrl;
+		triggersApplied = true;
+	}
+	if (stagingTraffic) {
+		staged = runWranglerVersionDeploy(root, stagingTraffic, options, "stage");
+		try {
+			applyTriggers();
+		} catch (error) {
+			throw withStagedVersionCleanupNote(error);
+		}
+		const targetUrl = resolveCdnWarmupTargetUrl(root, staged.deployedUrl ?? triggersDeployedUrl, options);
+		const headers = buildVersionOverrideHeaders(resolveWorkerNameForVersionOverride(wranglerConfig, options), upload.versionId);
+		if (targetUrl && headers) {
+			try {
+				await warmCdnCache({
+					targetUrl,
+					paths,
+					headers,
+					concurrency: options.warmCdnConcurrency,
+					timeoutMs: options.warmCdnTimeout,
+					retries: options.warmCdnRetries,
+					strict: options.warmCdnStrict
+				});
+			} catch (error) {
+				throw withStagedVersionCleanupNote(error);
+			}
+			warmedBeforePromotion = true;
+		} else if (options.warmCdnStrict) throw new Error("CDN warmup failed: pre-traffic warmup needs a production URL and Worker name for version overrides. Configure a route/custom domain and Worker name, or rerun without --warm-cdn-strict. " + getStagedVersionCleanupNote());
+	} else console.warn("  CDN warmup: pre-traffic version override skipped because the current deployment is not a single 100% version.");
+	const deployed = runWranglerVersionDeploy(root, [{
+		versionId: upload.versionId,
+		percentage: 100
+	}], options, warmedBeforePromotion ? "promote-warmed" : "promote-uploaded");
+	if (!warmedBeforePromotion) {
+		try {
+			applyTriggers();
+		} catch (error) {
+			throw withPromotedVersionTriggerNote(error);
+		}
+		const targetUrl = resolveCdnWarmupTargetUrl(root, deployed.deployedUrl ?? triggersDeployedUrl, options);
+		if (targetUrl) await warmCdnCache({
+			targetUrl,
+			paths,
+			concurrency: options.warmCdnConcurrency,
+			timeoutMs: options.warmCdnTimeout,
+			retries: options.warmCdnRetries,
+			strict: options.warmCdnStrict
+		});
+		else if (options.warmCdnStrict) throw new Error("CDN warmup failed: no production URL could be inferred from wrangler config or output. Configure a route/custom domain, ensure Wrangler prints a workers.dev URL, or rerun without --warm-cdn-strict.");
+		else console.warn("  CDN warmup skipped: no production URL could be inferred from wrangler config or output.");
+	}
+	return deployed.deployedUrl ?? triggersDeployedUrl ?? staged?.deployedUrl ?? upload.previewUrl ?? "(URL not detected in wrangler output)";
+}
+function resolveCdnWarmupTargetUrl(root, deployedUrl, options) {
+	const config = parseWranglerConfig(root, options?.config);
+	const env = getWranglerTargetEnv(options ?? {});
+	const customDomain = (env ? config?.env?.[env]?.customDomain : void 0) ?? config?.customDomain;
+	if (customDomain) return `https://${customDomain}`;
+	return deployedUrl;
+}
+function readWranglerDeploymentStatus(root, options) {
+	try {
+		return runWranglerDeploymentStatus(root, options);
+	} catch {
+		return null;
+	}
+}
+function getZeroPercentStagingTraffic(deployment, versionId) {
+	const current = deployment?.versions ?? [];
+	if (current.length !== 1 || current[0].percentage !== 100) return null;
+	if (current[0].versionId === versionId) return null;
+	return [current[0], {
+		versionId,
+		percentage: 0
+	}];
+}
+function getWranglerTargetEnv(options) {
+	return options.env || (options.preview ? "preview" : void 0);
+}
+function resolveWorkerNameForVersionOverride(config, options) {
+	if (options.name) return options.name;
+	const env = getWranglerTargetEnv(options);
+	if (!env) return config?.name;
+	if (config?.legacyEnv === false) return config.name;
+	return config?.env?.[env]?.name ?? (config?.name ? `${config.name}-${env}` : void 0);
+}
+function quoteStructuredHeaderString(value) {
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+function buildVersionOverrideHeaders(workerName, versionId) {
+	if (!workerName) return void 0;
+	return { "Cloudflare-Workers-Version-Overrides": `${workerName}=${quoteStructuredHeaderString(versionId)}` };
+}
+function withStagedVersionCleanupNote(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error(`${message} ${getStagedVersionCleanupNote()}`, { cause: error });
+}
+function getStagedVersionCleanupNote() {
+	return "The uploaded version may remain staged at 0% with the previous version still serving 100% traffic; rerun deploy to promote it or use `wrangler versions deploy` to choose the desired version split.";
+}
+function withPromotedVersionTriggerNote(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error(`${message} The uploaded version may already be promoted to 100%, but Worker triggers/routes may not be updated; rerun deploy or \`wrangler triggers deploy\` after fixing the trigger error.`, { cause: error });
 }
 async function deploy(options) {
 	const deployEnv = validateWranglerEnvName(options.env || (options.preview ? "preview" : "production"));
@@ -229,44 +494,81 @@ async function deploy(options) {
 		return;
 	}
 	const buildEnv = deployEnv === "production" && !options.env ? void 0 : deployEnv;
+	const viteConfigMetadata = await withCloudflareEnv(buildEnv, () => loadDeployViteConfigMetadata(info.root));
+	const nextConfig = await withCloudflareEnv(buildEnv, async () => {
+		const inlineNextConfig = viteConfigMetadata.nextConfig;
+		return resolveNextConfig(inlineNextConfig ? await resolveNextConfigInput(inlineNextConfig, PHASE_PRODUCTION_BUILD) : await loadNextConfig(info.root, PHASE_PRODUCTION_BUILD), info.root);
+	});
+	const vinextPrerenderConfig = !options.prerenderAll && nextConfig.output !== "export" ? viteConfigMetadata.prerenderConfig : null;
+	const prerenderDecision = resolveVinextPrerenderDecision({
+		prerenderAllFlag: options.prerenderAll,
+		vinextPrerenderConfig,
+		nextOutput: nextConfig.output
+	});
+	const shouldEmitPrerenderPathManifest = options.warmCdnCache || !options.skipBuild && prerenderDecision;
 	if (!options.skipBuild) await runBuild(info, buildEnv);
 	else console.log("\n  Skipping build (--skip-build)");
-	{
-		const nextConfig = await resolveNextConfig(await loadNextConfig(info.root), info.root);
-		const vinextPrerenderConfig = !options.prerenderAll && nextConfig.output !== "export" ? await withCloudflareEnv(buildEnv, async () => {
-			return loadVinextPrerenderConfigFromViteConfig(await loadProjectViteApi(info.root), info.root);
-		}) : null;
-		const prerenderDecision = resolveVinextPrerenderDecision({
-			prerenderAllFlag: options.prerenderAll,
-			vinextPrerenderConfig,
-			nextOutput: nextConfig.output
-		});
-		if (prerenderDecision) {
-			console.log(`\n  ${formatVinextPrerenderLabel(prerenderDecision)}`);
-			if (nextConfig.enablePrerenderSourceMaps) {
-				process.setSourceMapsEnabled(true);
-				Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 50);
-			}
-			await runPrerender({
-				root: info.root,
-				concurrency: options.prerenderConcurrency
-			});
+	if (shouldEmitPrerenderPathManifest) await emitPrerenderPathManifest({
+		root: info.root,
+		nextConfig,
+		routeRootConfig: viteConfigMetadata.routeRootConfig
+	});
+	let ranPrerender = false;
+	if (prerenderDecision) {
+		console.log(`\n  ${formatVinextPrerenderLabel(prerenderDecision)}`);
+		if (nextConfig.enablePrerenderSourceMaps) {
+			process.setSourceMapsEnabled(true);
+			Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 50);
 		}
+		await runPrerender({
+			root: info.root,
+			concurrency: options.prerenderConcurrency,
+			nextConfig
+		});
+		ranPrerender = true;
+	}
+	if (ranPrerender) try {
+		await populateKVCacheFromPrerenderedArtifacts(root, deployEnv === "production" && !options.env ? void 0 : deployEnv, viteConfigMetadata.cacheConfig);
+	} catch (error) {
+		console.log(`  KV cache: Skipping prerender upload (${formatUnknownError(error)}). Continuing with deploy.`);
 	}
 	if (options.experimentalTPR) {
 		console.log();
 		const tprResult = await runTPR({
 			root,
+			config: options.config,
 			coverage: Math.max(1, Math.min(100, options.tprCoverage ?? 90)),
 			limit: Math.max(1, options.tprLimit ?? 1e3),
 			window: Math.max(1, options.tprWindow ?? 24)
 		});
 		if (tprResult.skipped) console.log(`  TPR: Skipped (${tprResult.skipped})`);
 	}
-	const url = runWranglerDeploy(root, { env: deployEnv === "production" && !options.env ? void 0 : deployEnv });
+	const wranglerOptions = {
+		env: deployEnv === "production" && !options.env ? void 0 : deployEnv,
+		name: options.name,
+		config: options.config
+	};
+	let url;
+	if (options.warmCdnCache) {
+		const warmPaths = readPrerenderWarmPaths(root, {
+			includeFallbackShells: options.warmCdnIncludeFallbacks,
+			strict: options.warmCdnStrict
+		});
+		if (warmPaths.length > 0) url = await deployWithCdnWarmup(root, warmPaths, {
+			...wranglerOptions,
+			warmCdnConcurrency: options.warmCdnConcurrency,
+			warmCdnTimeout: options.warmCdnTimeout,
+			warmCdnRetries: options.warmCdnRetries,
+			warmCdnStrict: options.warmCdnStrict
+		});
+		else {
+			console.log("\n  CDN warmup skipped: no build-discovered paths found.");
+			url = await runWranglerDeploy(root, wranglerOptions);
+		}
+	} else url = await runWranglerDeploy(root, wranglerOptions);
 	console.log("\n  ─────────────────────────────────────────");
 	console.log(`  Deployed to: ${url}`);
 	console.log("  ─────────────────────────────────────────\n");
 }
 //#endregion
-export { buildNodeCliInvocation, buildWranglerDeployArgs, buildWranglerInvocation, deploy, parseDeployArgs, resolveWranglerBin, runWranglerDeploy, validateWranglerEnvName, withCloudflareEnv };
+export { buildNodeCliInvocation, buildVersionOverrideHeaders, buildWranglerDeployArgs, buildWranglerInvocation, buildWranglerKVBulkPutArgs, deploy, deployWithCdnWarmup, getZeroPercentStagingTraffic, parseDeployArgs, resolveCdnWarmupTargetUrl, resolveWorkerNameForVersionOverride, resolveWranglerBin, runWranglerDeploy, runWranglerKVBulkPut, validateWranglerEnvName, withCloudflareEnv };

package/dist/prerender-kv-populate.d.ts

@@ -0,0 +1,25 @@
+//#region src/prerender-kv-populate.d.ts
+/**
+ * Deploy-time KV population for App Router prerendered artifacts.
+ *
+ * Reads `dist/server/vinext-prerender.json` and `dist/server/prerendered-routes/*`,
+ * converts rendered App Router HTML/RSC artifacts into the same serialized
+ * KVCacheEntry shape written by KVCacheHandler.set(), and returns Wrangler KV
+ * bulk import records for deploy-time upload.
+ */
+type KVBulkPair = {
+  key: string;
+  value: string;
+  expiration_ttl?: number;
+  metadata?: Record<string, unknown>;
+};
+declare function buildPrerenderKVPairs(serverDir: string, options?: {
+  appPrefix?: string;
+  now?: number;
+  ttlSeconds?: number;
+}): {
+  routeCount: number;
+  pairs: KVBulkPair[];
+};
+//#endregion
+export { KVBulkPair, buildPrerenderKVPairs };

package/dist/prerender-kv-populate.js

@@ -0,0 +1,120 @@
+import { ENTRY_PREFIX } from "./cache/kv-data-adapter.runtime.js";
+import path from "node:path";
+import fs from "node:fs";
+import { getRenderedAppRoutes, readPrerenderManifest } from "vinext/internal/server/prerender-manifest";
+import { appIsrCacheKey } from "vinext/internal/server/isr-cache";
+import { buildAppPageCacheTags } from "vinext/internal/server/app-page-cache";
+import { normalizePregeneratedPathname } from "vinext/internal/server/pregenerated-concrete-paths";
+import { getOutputPath, getRscOutputPath } from "vinext/internal/utils/prerender-output-paths";
+//#region src/prerender-kv-populate.ts
+/**
+* Deploy-time KV population for App Router prerendered artifacts.
+*
+* Reads `dist/server/vinext-prerender.json` and `dist/server/prerendered-routes/*`,
+* converts rendered App Router HTML/RSC artifacts into the same serialized
+* KVCacheEntry shape written by KVCacheHandler.set(), and returns Wrangler KV
+* bulk import records for deploy-time upload.
+*/
+/** Default KV expiration TTL used by KVCacheHandler for revalidating entries. */
+const DEFAULT_KV_TTL_SECONDS = 720 * 3600;
+function resolveContainedFile(rootDir, relativePath) {
+	const resolvedRoot = path.resolve(rootDir);
+	const resolvedFile = path.resolve(resolvedRoot, relativePath);
+	const relative = path.relative(resolvedRoot, resolvedFile);
+	if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`[vinext] Refusing to read prerender artifact outside ${resolvedRoot}`);
+	return resolvedFile;
+}
+function formatUnknownError(error) {
+	if (error instanceof Error && error.message) return error.message;
+	return String(error);
+}
+function buildKVKey(appPrefix, cacheKey) {
+	return `${appPrefix ? `${appPrefix}:` : ""}${ENTRY_PREFIX}${cacheKey}`;
+}
+function buildCacheEntry(value, tags, now, revalidateSeconds, expireSeconds) {
+	const cacheControl = revalidateSeconds === void 0 ? void 0 : expireSeconds === void 0 ? { revalidate: revalidateSeconds } : {
+		revalidate: revalidateSeconds,
+		expire: expireSeconds
+	};
+	return JSON.stringify({
+		value,
+		tags,
+		lastModified: now,
+		revalidateAt: revalidateSeconds === void 0 ? null : now + revalidateSeconds * 1e3,
+		expireAt: expireSeconds === void 0 ? null : now + expireSeconds * 1e3,
+		...cacheControl ? { cacheControl } : {}
+	});
+}
+function buildMetadata(tags) {
+	const metadata = { tags };
+	return JSON.stringify(metadata).length <= 1024 ? metadata : void 0;
+}
+function buildPrerenderKVPairs(serverDir, options) {
+	const manifest = readPrerenderManifest(path.join(serverDir, "vinext-prerender.json"));
+	if (!manifest?.buildId || !Array.isArray(manifest.routes)) return {
+		routeCount: 0,
+		pairs: []
+	};
+	const prerenderDir = path.join(serverDir, "prerendered-routes");
+	if (!fs.existsSync(prerenderDir)) return {
+		routeCount: 0,
+		pairs: []
+	};
+	const pairs = [];
+	const now = options?.now ?? Date.now();
+	const ttlSeconds = options?.ttlSeconds ?? DEFAULT_KV_TTL_SECONDS;
+	const trailingSlash = manifest.trailingSlash ?? false;
+	let routeCount = 0;
+	for (const route of getRenderedAppRoutes(manifest.routes)) {
+		const artifactPathname = route.path ?? route.route;
+		const cachePathname = normalizePregeneratedPathname(artifactPathname);
+		let htmlPath;
+		let rscPath;
+		try {
+			htmlPath = resolveContainedFile(prerenderDir, getOutputPath(artifactPathname, trailingSlash));
+			rscPath = resolveContainedFile(prerenderDir, getRscOutputPath(artifactPathname));
+		} catch (error) {
+			console.warn(`[vinext] Skipping prerender KV seed for ${artifactPathname}: ${formatUnknownError(error)}`);
+			continue;
+		}
+		if (!fs.existsSync(htmlPath)) continue;
+		if (typeof route.revalidate === "number" && route.revalidate <= 0) continue;
+		const revalidateSeconds = typeof route.revalidate === "number" ? route.revalidate : void 0;
+		const expireSeconds = typeof route.expire === "number" ? route.expire : void 0;
+		const expirationTtl = revalidateSeconds === void 0 ? void 0 : ttlSeconds;
+		const tags = buildAppPageCacheTags(cachePathname, []);
+		const metadata = buildMetadata(tags);
+		const htmlKey = appIsrCacheKey(cachePathname, "html", manifest.buildId);
+		const rscKey = appIsrCacheKey(cachePathname, "rsc", manifest.buildId);
+		pairs.push({
+			key: buildKVKey(options?.appPrefix, htmlKey),
+			value: buildCacheEntry({
+				kind: "APP_PAGE",
+				html: fs.readFileSync(htmlPath, "utf-8"),
+				headers: route.headers
+			}, tags, now, revalidateSeconds, expireSeconds),
+			...expirationTtl !== void 0 ? { expiration_ttl: expirationTtl } : {},
+			...metadata ? { metadata } : {}
+		});
+		if (fs.existsSync(rscPath)) {
+			const rscData = fs.readFileSync(rscPath).toString("base64");
+			pairs.push({
+				key: buildKVKey(options?.appPrefix, rscKey),
+				value: buildCacheEntry({
+					kind: "APP_PAGE",
+					html: "",
+					rscData
+				}, tags, now, revalidateSeconds, expireSeconds),
+				...expirationTtl !== void 0 ? { expiration_ttl: expirationTtl } : {},
+				...metadata ? { metadata } : {}
+			});
+		}
+		routeCount++;
+	}
+	return {
+		routeCount,
+		pairs
+	};
+}
+//#endregion
+export { buildPrerenderKVPairs };

package/dist/tpr.d.ts

@@ -21,7 +21,8 @@
  * or no KV namespace is configured.
  */
 type TPROptions = {
-  /** Project root directory. */root: string; /** Traffic coverage percentage (0–100). Default: 90. */
+  /** Project root directory. */root: string; /** Wrangler config path, relative to root unless absolute. */
+  config?: string; /** Traffic coverage percentage (0–100). Default: 90. */
   coverage: number; /** Hard cap on number of pages to pre-render. Default: 1000. */
   limit: number; /** Analytics lookback window in hours. Default: 24. */
   window: number;
@@ -42,12 +43,19 @@ type WranglerConfig = {
   accountId?: string;
   kvNamespaceId?: string;
   customDomain?: string;
+  name?: string;
+  legacyEnv?: boolean;
+  env?: Record<string, WranglerEnvironmentConfig>;
+};
+type WranglerEnvironmentConfig = {
+  customDomain?: string;
+  name?: string;
 };
 /**
  * Parse wrangler config (JSONC or TOML) to extract the fields TPR needs:
  * account_id, VINEXT_KV_CACHE KV namespace ID, and custom domain.
  */
-declare function parseWranglerConfig(root: string): WranglerConfig | null;
+declare function parseWranglerConfig(root: string, configPath?: string): WranglerConfig | null;
 /**
  * Generate zone lookup candidates from shortest (2-part) to longest.
  * Tries the most common case first (e.g., "example.com") and progressively
@@ -80,4 +88,4 @@ declare function buildTprKVPairs(entries: Map<string, PrerenderResult>, buildId:
  */
 declare function runTPR(options: TPROptions): Promise<TPRResult>;
 //#endregion
-export { TPROptions, TPRResult, buildTprKVPairs, domainCandidates, parseWranglerConfig, resolveVinextProdServerPath, runTPR };
+export { TPROptions, TPRResult, WranglerEnvironmentConfig, buildTprKVPairs, domainCandidates, parseWranglerConfig, resolveVinextProdServerPath, runTPR };