@vinext/cloudflare 0.1.2 → 0.2.1

package/dist/deploy.js

@@ -0,0 +1,272 @@
+import { runTPR } from "./tpr.js";
+import { formatImageOptimizationHint, formatMissingCacheAdapterError, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler } from "./deploy-config.js";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } 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 { detectProject, findInNodeModules, formatMissingCloudflarePluginError, getMissingDeps } from "vinext/internal/utils/project";
+//#region src/deploy.ts
+/**
+* vinext-cloudflare deploy — one-command Cloudflare Workers deployment.
+*
+* Takes any Next.js app and deploys it to Cloudflare Workers:
+*
+*   1. Validates the project was prepared by `vinext init --platform=cloudflare`
+*   2. Runs the Vite build
+*   3. Deploys to Cloudflare Workers via Wrangler
+*/
+function parsePositiveIntegerArg(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 positive integer, but got "${raw}".`);
+	return parsed;
+}
+/** Deploy command flag definitions for util.parseArgs. */
+const deployArgOptions = {
+	help: {
+		type: "boolean",
+		short: "h",
+		default: false
+	},
+	preview: {
+		type: "boolean",
+		default: false
+	},
+	env: { type: "string" },
+	name: { type: "string" },
+	"skip-build": {
+		type: "boolean",
+		default: false
+	},
+	"dry-run": {
+		type: "boolean",
+		default: false
+	},
+	"prerender-all": {
+		type: "boolean",
+		default: false
+	},
+	"prerender-concurrency": { type: "string" },
+	"experimental-tpr": {
+		type: "boolean",
+		default: false
+	},
+	"tpr-coverage": { type: "string" },
+	"tpr-limit": { type: "string" },
+	"tpr-window": { type: "string" }
+};
+function parseDeployArgs(args) {
+	const { values } = parseArgs({
+		args,
+		options: deployArgOptions,
+		strict: true
+	});
+	function parseIntArg(name, raw) {
+		if (!raw) return void 0;
+		const n = parseInt(raw, 10);
+		if (isNaN(n)) {
+			console.error(`  --${name} must be a number (got: ${raw})`);
+			process.exit(1);
+		}
+		return n;
+	}
+	return {
+		help: values.help,
+		preview: values.preview,
+		env: values.env?.trim() || void 0,
+		name: values.name?.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"),
+		experimentalTPR: values["experimental-tpr"],
+		tprCoverage: parseIntArg("tpr-coverage", values["tpr-coverage"]),
+		tprLimit: parseIntArg("tpr-limit", values["tpr-limit"]),
+		tprWindow: parseIntArg("tpr-window", values["tpr-window"])
+	};
+}
+/**
+* Run a function with `process.env.CLOUDFLARE_ENV` set to the given value,
+* restoring the previous state (whether set or absent) after the function
+* resolves or throws.
+*
+* The `@cloudflare/vite-plugin` reads `CLOUDFLARE_ENV` from `process.env` to
+* drive the multi-environment merge applied to the emitted `wrangler.json`.
+* Without this propagation the `--env <name>` CLI flag is silently ignored at
+* build time and the top-level config is emitted regardless. See issue #1210.
+*
+* Passing `undefined` is a no-op; the callback runs with `process.env` untouched.
+*/
+async function withCloudflareEnv(env, fn) {
+	if (env === void 0 || env === "") return fn();
+	const hadPrev = "CLOUDFLARE_ENV" in process.env;
+	const prev = process.env.CLOUDFLARE_ENV;
+	process.env.CLOUDFLARE_ENV = env;
+	try {
+		return await fn();
+	} finally {
+		if (hadPrev) process.env.CLOUDFLARE_ENV = prev;
+		else delete process.env.CLOUDFLARE_ENV;
+	}
+}
+async function loadProjectViteApi(root) {
+	let vitePath;
+	try {
+		vitePath = createRequire(path.join(root, "package.json")).resolve("vite");
+	} catch {
+		vitePath = "vite";
+	}
+	return await (vitePath === "vite" ? import(vitePath) : import(pathToFileURL(vitePath).href));
+}
+async function runBuild(info, env) {
+	console.log("\n  Building for Cloudflare Workers...\n");
+	const { createBuilder } = await loadProjectViteApi(info.root);
+	await withCloudflareEnv(env, async () => {
+		await (await createBuilder({ root: info.root })).buildApp();
+	});
+}
+function validateWranglerEnvName(env) {
+	if (env.includes("\0")) throw new Error("Wrangler environment names cannot contain null bytes.");
+	return env;
+}
+function buildWranglerDeployArgs(options) {
+	const args = ["deploy"];
+	const env = options.env || (options.preview ? "preview" : void 0);
+	if (env) args.push("--env", validateWranglerEnvName(env));
+	return {
+		args,
+		env
+	};
+}
+/**
+* Resolve Wrangler's JavaScript CLI entrypoint in node_modules.
+*
+* Invoking the JavaScript file through `process.execPath` avoids the `.cmd`
+* shim and command shell that package managers create on Windows.
+*/
+function resolveWranglerBin(root, resolvePackageJson = (projectRoot) => {
+	try {
+		return createRequire(path.join(projectRoot, "package.json")).resolve("wrangler/package.json");
+	} catch {
+		return findInNodeModules(projectRoot, "wrangler/package.json");
+	}
+}) {
+	const packageJsonPath = resolvePackageJson(root);
+	if (packageJsonPath) {
+		const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+		const bin = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.wrangler;
+		if (bin) return path.resolve(path.dirname(packageJsonPath), bin);
+	}
+	return path.join(root, "node_modules", "wrangler", "bin", "wrangler.js");
+}
+function buildNodeCliInvocation(scriptPath, args, nodeExecutable = process.execPath) {
+	return {
+		file: nodeExecutable,
+		args: [scriptPath, ...args]
+	};
+}
+function buildWranglerInvocation(root, options, nodeExecutable = process.execPath) {
+	const wranglerBin = resolveWranglerBin(root);
+	const { args, env } = buildWranglerDeployArgs(options);
+	return {
+		...buildNodeCliInvocation(wranglerBin, args, nodeExecutable),
+		env
+	};
+}
+function runWranglerDeploy(root, options, execute = execFileSync) {
+	const execOpts = {
+		cwd: root,
+		stdio: "pipe",
+		encoding: "utf-8",
+		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)";
+}
+async function deploy(options) {
+	const deployEnv = validateWranglerEnvName(options.env || (options.preview ? "preview" : "production"));
+	const root = path.resolve(options.root);
+	loadDotenv({
+		root,
+		mode: "production"
+	});
+	console.log("\n  vinext-cloudflare deploy\n");
+	const info = detectProject(root);
+	if (!info.isAppRouter && !info.isPagesRouter) {
+		console.error("  Error: No app/ or pages/ directory found.");
+		console.error("  vinext-cloudflare deploy requires a Next.js project with an app/ or pages/ directory");
+		console.error("  (also checks src/app/ and src/pages/).\n");
+		process.exit(1);
+	}
+	if (options.name) info.projectName = options.name;
+	console.log(`  Project: ${info.projectName}`);
+	console.log(`  Router:  ${info.isAppRouter ? "App Router" : "Pages Router"}`);
+	console.log(`  ISR:     ${info.hasISR ? "detected" : "none"}`);
+	const missingScaffolding = [!info.hasViteConfig && "Vite config", !info.hasWranglerConfig && "Wrangler config"].filter((value) => Boolean(value));
+	if (missingScaffolding.length > 0) throw new Error(`Missing Cloudflare deployment setup: ${missingScaffolding.join(", ")}. Run \`vinext init --platform=cloudflare\` first.`);
+	const missingDeps = getMissingDeps(info);
+	if (missingDeps.length > 0) throw new Error(`Missing deployment dependencies: ${missingDeps.map((dependency) => dependency.name).join(", ")}. Run \`vinext init --platform=cloudflare\` first.`);
+	if (info.hasViteConfig && !viteConfigHasCloudflarePlugin(root)) throw new Error(formatMissingCloudflarePluginError({ isAppRouter: info.isAppRouter }));
+	if (info.hasISR && !viteConfigHasCacheAdapter(root) && !workerEntryHasCacheHandler(root)) throw new Error(formatMissingCacheAdapterError({}));
+	if (!viteConfigHasImageAdapter(root)) {
+		console.log();
+		console.log(formatImageOptimizationHint());
+	}
+	if (options.dryRun) {
+		console.log("\n  Dry run complete. No build or deploy performed.\n");
+		return;
+	}
+	const buildEnv = deployEnv === "production" && !options.env ? void 0 : deployEnv;
+	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 (options.experimentalTPR) {
+		console.log();
+		const tprResult = await runTPR({
+			root,
+			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 });
+	console.log("\n  ─────────────────────────────────────────");
+	console.log(`  Deployed to: ${url}`);
+	console.log("  ─────────────────────────────────────────\n");
+}
+//#endregion
+export { buildNodeCliInvocation, buildWranglerDeployArgs, buildWranglerInvocation, deploy, parseDeployArgs, resolveWranglerBin, runWranglerDeploy, validateWranglerEnvName, withCloudflareEnv };

package/dist/images/images-optimizer.d.ts

@@ -0,0 +1,28 @@
+//#region src/images/images-optimizer.d.ts
+/** Options accepted by {@link imagesOptimizer}, forwarded to the runtime factory. */
+type ImagesOptimizerOptions = {
+  /** Cloudflare Images binding name on the Worker `env`. @default "IMAGES" */binding?: string;
+};
+/**
+ * Config-time builder: returns a serializable descriptor whose `adapter` is the
+ * absolute path to the runtime factory. Safe to call from vite.config — it
+ * never instantiates the optimizer or reads a binding.
+ *
+ * Wires `next/image` optimization (`/_next/image`) to the Cloudflare Images
+ * binding for on-the-fly resize, format negotiation (AVIF/WebP), and quality
+ * transforms at the edge — no custom worker entry required.
+ *
+ * @example
+ * import { vinext } from "vinext";
+ * import { imagesOptimizer } from "@vinext/cloudflare/images/images-optimizer";
+ *
+ * export default defineConfig({
+ *   plugins: [vinext({ images: { optimizer: imagesOptimizer() } })],
+ * });
+ */
+declare function imagesOptimizer(options?: ImagesOptimizerOptions): {
+  adapter: string;
+  options: ImagesOptimizerOptions | undefined;
+};
+//#endregion
+export { ImagesOptimizerOptions, imagesOptimizer };

package/dist/images/images-optimizer.js

@@ -0,0 +1,28 @@
+import { fileURLToPath } from "node:url";
+//#region src/images/images-optimizer.ts
+/**
+* Config-time builder: returns a serializable descriptor whose `adapter` is the
+* absolute path to the runtime factory. Safe to call from vite.config — it
+* never instantiates the optimizer or reads a binding.
+*
+* Wires `next/image` optimization (`/_next/image`) to the Cloudflare Images
+* binding for on-the-fly resize, format negotiation (AVIF/WebP), and quality
+* transforms at the edge — no custom worker entry required.
+*
+* @example
+* import { vinext } from "vinext";
+* import { imagesOptimizer } from "@vinext/cloudflare/images/images-optimizer";
+*
+* export default defineConfig({
+*   plugins: [vinext({ images: { optimizer: imagesOptimizer() } })],
+* });
+*/
+function imagesOptimizer(options) {
+	if (options?.binding !== void 0 && typeof options.binding !== "string") throw new TypeError("[vinext] imagesOptimizer({ binding }) must be a string Images binding name.");
+	return {
+		adapter: fileURLToPath(import.meta.resolve("./images-optimizer.runtime.js")),
+		options
+	};
+}
+//#endregion
+export { imagesOptimizer };

package/dist/images/images-optimizer.runtime.d.ts

@@ -0,0 +1,16 @@
+import { ImageOptimizer } from "vinext/server/image-optimization";
+
+//#region src/images/images-optimizer.runtime.d.ts
+/** Options accepted by the optimizer factory (mirrors `ImagesOptimizerOptions`). */
+type ImagesOptimizerOptions = {
+  binding?: string;
+};
+declare const createCloudflareImageOptimizer: ({
+  env,
+  options
+}: {
+  env?: Record<string, unknown>;
+  options?: ImagesOptimizerOptions;
+}) => ImageOptimizer;
+//#endregion
+export { createCloudflareImageOptimizer as default };

package/dist/images/images-optimizer.runtime.js

@@ -0,0 +1,16 @@
+//#region src/images/images-optimizer.runtime.ts
+/** Default Cloudflare Images binding name on the Worker `env`. */
+const DEFAULT_BINDING = "IMAGES";
+const createCloudflareImageOptimizer = ({ env, options }) => {
+	const binding = options?.binding ?? DEFAULT_BINDING;
+	const images = env?.[binding];
+	if (!images || typeof images.input !== "function") throw new Error(`[vinext] The Cloudflare image optimizer requires an \`${binding}\` Images binding.\n  Add it to wrangler.jsonc:\n    "images": { "binding": "${binding}" }`);
+	return { async transformImage(body, { width, format, quality }) {
+		return (await images.input(body).transform(width > 0 ? { width } : {}).output({
+			format,
+			quality
+		})).response();
+	} };
+};
+//#endregion
+export { createCloudflareImageOptimizer as default };

package/dist/tpr.d.ts

@@ -0,0 +1,83 @@
+//#region src/tpr.d.ts
+/**
+ * TPR: Traffic-aware Pre-Rendering
+ *
+ * Uses Cloudflare zone analytics to determine which pages actually get
+ * traffic, and pre-renders only those during deploy. The pre-rendered
+ * HTML is uploaded to KV in the same format ISR uses at runtime — no
+ * runtime changes needed.
+ *
+ * Flow:
+ *   1. Parse wrangler config to find custom domain and KV namespace
+ *   2. Resolve the Cloudflare zone for the custom domain
+ *   3. Query zone analytics (GraphQL) for top pages by request count
+ *   4. Walk ranked list until coverage threshold is met
+ *   5. Start the built production server locally
+ *   6. Fetch each hot route to produce HTML
+ *   7. Upload pre-rendered HTML to KV (same KVCacheEntry format ISR reads)
+ *
+ * TPR is an experimental feature enabled via --experimental-tpr. It
+ * gracefully skips when no custom domain, no API token, no traffic data,
+ * or no KV namespace is configured.
+ */
+type TPROptions = {
+  /** Project root directory. */root: 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;
+};
+type TPRResult = {
+  /** Total unique page paths found in analytics. */totalPaths: number; /** Number of pages successfully pre-rendered and uploaded. */
+  prerenderedCount: number; /** Actual traffic coverage achieved (percentage). */
+  coverageAchieved: number; /** Wall-clock duration of the TPR step in milliseconds. */
+  durationMs: number; /** If TPR was skipped, the reason. */
+  skipped?: string;
+};
+type PrerenderResult = {
+  html: string;
+  status: number;
+  headers: Record<string, string>;
+};
+type WranglerConfig = {
+  accountId?: string;
+  kvNamespaceId?: string;
+  customDomain?: 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;
+/**
+ * Generate zone lookup candidates from shortest (2-part) to longest.
+ * Tries the most common case first (e.g., "example.com") and progressively
+ * adds labels for multi-part TLDs (e.g., "co.uk" → "example.co.uk").
+ *
+ * "shop.example.com"    → ["example.com", "shop.example.com"]
+ * "shop.example.co.uk"  → ["co.uk", "example.co.uk", "shop.example.co.uk"]
+ * "example.com"         → ["example.com"]
+ */
+declare function domainCandidates(domain: string): string[];
+declare function resolveVinextProdServerPath(root: string): string;
+/**
+ * Build KV bulk API pairs from pre-rendered entries.
+ *
+ * Key format matches the runtime KVCacheHandler exactly:
+ *   ENTRY_PREFIX + isrCacheKey("app", pathname, buildId) + ":html"
+ *   → "cache:app:<buildId>:<pathname>:html"
+ */
+declare function buildTprKVPairs(entries: Map<string, PrerenderResult>, buildId: string | undefined, defaultRevalidateSeconds: number): Array<{
+  key: string;
+  value: string;
+  expiration_ttl: number;
+}>;
+/**
+ * Run the TPR pipeline: query traffic, select routes, pre-render, upload.
+ *
+ * Designed to be called between the build step and wrangler deploy in the
+ * `vinext-cloudflare deploy` pipeline. Gracefully skips (never errors) when
+ * the prerequisites aren't met.
+ */
+declare function runTPR(options: TPROptions): Promise<TPRResult>;
+//#endregion
+export { TPROptions, TPRResult, buildTprKVPairs, domainCandidates, parseWranglerConfig, resolveVinextProdServerPath, runTPR };