@vinext/cloudflare 0.1.2 → 0.2.0

package/README.md

@@ -1,13 +1,15 @@
 # @vinext/cloudflare
 
-Cloudflare cache adapters for [vinext](https://www.npmjs.com/package/vinext).
+Cloudflare deployment tools and runtime adapters for
+[vinext](https://www.npmjs.com/package/vinext).
 
-This package provides the Cloudflare-specific cache backends that vinext uses for
-ISR and the `"use cache"` data cache when deploying to Cloudflare Workers:
+This package provides Cloudflare-specific cache and image backends for vinext:
 
 - **`kvDataAdapter()`** (`@vinext/cloudflare/cache/kv-data-adapter`) — backs the
   data cache (`fetch`, `"use cache"`, `unstable_cache`) with a Workers KV
-  namespace. Also used for ISR in the absence of a cdn adapter.
+  namespace. Also used for ISR in the absence of a CDN adapter.
+- **`imagesOptimizer()`** (`@vinext/cloudflare/images/images-optimizer`) — backs
+  `next/image` transformations with a Cloudflare Images binding.
 
 ## Usage
 
@@ -15,6 +17,7 @@ Declare the adapters on the `vinext()` plugin in your Vite config:
 
 ```ts
 import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
+import { imagesOptimizer } from "@vinext/cloudflare/images/images-optimizer";
 
 export default defineConfig({
   plugins: [
@@ -22,8 +25,20 @@ export default defineConfig({
       cache: {
         data: kvDataAdapter(), // KV-backed data cache (binding: VINEXT_KV_CACHE)
       },
+      images: { optimizer: imagesOptimizer() }, // Cloudflare Images binding: IMAGES
     }),
     cloudflare(),
   ],
 });
 ```
+
+## Deploy
+
+Deploy Cloudflare Workers projects with the package CLI:
+
+```sh
+npx @vinext/cloudflare deploy
+```
+
+With Vite+, use `vpx @vinext/cloudflare deploy`, or
+`vp exec vinext-cloudflare deploy` when running the locally installed bin.

package/dist/cache/kv-data-adapter.runtime.js

@@ -1,6 +1,6 @@
 import { isUnknownRecord, readCacheControlNumberField } from "../utils/cache-control-metadata.js";
-import { getRequestExecutionContext } from "vinext/shims/request-context";
 import { Buffer } from "node:buffer";
+import { getRequestExecutionContext } from "vinext/shims/request-context";
 //#region src/cache/kv-data-adapter.runtime.ts
 /**
 * Cloudflare KV data cache — implementation + runtime factory.

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { deploy, parseDeployArgs } from "./deploy.js";
+import { printDeployHelp } from "./deploy-help.js";
+import fs from "node:fs";
+//#region src/cli.ts
+const VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version;
+const command = process.argv[2];
+const rawArgs = process.argv.slice(3);
+function printHelp(commandName) {
+	if (commandName === "deploy") {
+		printDeployHelp();
+		return;
+	}
+	console.log(`
+  vinext-cloudflare v${VERSION}
+
+  Usage: vinext-cloudflare <command> [options]
+
+  Vite+:
+    vpx @vinext/cloudflare <command>       Run by package name
+    vp exec vinext-cloudflare <command>    Run the locally installed bin
+
+  Commands:
+    deploy   Deploy to Cloudflare Workers
+
+  Options:
+    -h, --help     Show this help
+    --version      Show version
+`);
+}
+async function deployCommand() {
+	const parsed = parseDeployArgs(rawArgs);
+	if (parsed.help) {
+		printHelp("deploy");
+		return;
+	}
+	await deploy({
+		root: process.cwd(),
+		preview: parsed.preview,
+		env: parsed.env,
+		skipBuild: parsed.skipBuild,
+		dryRun: parsed.dryRun,
+		name: parsed.name,
+		prerenderAll: parsed.prerenderAll,
+		prerenderConcurrency: parsed.prerenderConcurrency,
+		experimentalTPR: parsed.experimentalTPR,
+		tprCoverage: parsed.tprCoverage,
+		tprLimit: parsed.tprLimit,
+		tprWindow: parsed.tprWindow
+	});
+}
+if (command === "--version" || command === "-v") {
+	console.log(`vinext-cloudflare v${VERSION}`);
+	process.exit(0);
+}
+if (command === "--help" || command === "-h" || !command) {
+	printHelp();
+	process.exit(0);
+}
+switch (command) {
+	case "deploy":
+		deployCommand().catch((error) => {
+			console.error(error);
+			process.exit(1);
+		});
+		break;
+	default:
+		console.error(`Unknown command: ${command}`);
+		printHelp();
+		process.exit(1);
+}
+//#endregion
+export {};

package/dist/deploy-config.d.ts

@@ -0,0 +1,47 @@
+//#region src/deploy-config.d.ts
+/**
+ * Check whether an existing vite.config file already imports and uses the
+ * Cloudflare Vite plugin. This is a heuristic text scan — it doesn't execute
+ * the config — so it may produce false negatives for unusual configurations.
+ *
+ * Returns true when the config both imports the package and invokes
+ * `cloudflare(...)` in the plugin list.
+ */
+declare function viteConfigHasCloudflarePlugin(root: string): boolean;
+/**
+ * Detect whether the Vite config assigns a CDN or data cache adapter — i.e. the
+ * `cdn` or `data` field of the `vinext({ cache })` option is given a value.
+ * This is a source-level check on those exact object fields, not a fuzzy scan
+ * for adapter names. Mirrors {@link viteConfigHasCloudflarePlugin}'s leniency:
+ * an unreadable or absent config is treated as configured so a deploy is never
+ * blocked on a false negative.
+ */
+declare function viteConfigHasCacheAdapter(root: string): boolean;
+declare function viteConfigHasImageAdapter(root: string): boolean;
+/**
+ * Detect whether an existing user-authored Worker entry wires up a cache
+ * backend imperatively via one of the `setCacheHandler` / `setDataCacheHandler`
+ * / `setCdnCacheAdapter` setters. These setters are deprecated in favour of the
+ * declarative `vinext({ cache })` option, but older apps that scaffolded a KV
+ * cache handler into their Worker entry must keep working — so a deploy should
+ * not be blocked when the Worker entry already configures a backend.
+ *
+ * This is a heuristic text scan (it doesn't execute the entry), mirroring
+ * {@link viteConfigHasCacheAdapter}'s leniency: an unreadable Worker entry is
+ * treated as configured so a deploy is never blocked on a false negative. A
+ * missing Worker entry returns false (nothing to inspect — defer to other
+ * checks).
+ */
+declare function workerEntryHasCacheHandler(root: string): boolean;
+/**
+ * Build the error thrown when an ISR/cached app is deployed without a cache
+ * adapter configured in the Vite config. Production deployments need a
+ * persistent cache backend; vinext no longer scaffolds one into the Worker
+ * entry, so it must be declared via `vinext({ cache })`.
+ */
+declare function formatMissingCacheAdapterError(options: {
+  configFile?: string;
+}): string;
+declare function formatImageOptimizationHint(): string;
+//#endregion
+export { formatImageOptimizationHint, formatMissingCacheAdapterError, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler };

package/dist/deploy-config.js

@@ -0,0 +1,150 @@
+import fs from "node:fs";
+import path from "node:path";
+import { findViteConfigPath } from "vinext/internal/utils/project";
+//#region src/deploy-config.ts
+function escapeRegExp(value) {
+	return value.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+}
+/**
+* Check whether an existing vite.config file already imports and uses the
+* Cloudflare Vite plugin. This is a heuristic text scan — it doesn't execute
+* the config — so it may produce false negatives for unusual configurations.
+*
+* Returns true when the config both imports the package and invokes
+* `cloudflare(...)` in the plugin list.
+*/
+function viteConfigHasCloudflarePlugin(root) {
+	const configPath = findViteConfigPath(root);
+	if (!configPath) return false;
+	try {
+		const content = fs.readFileSync(configPath, "utf-8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+		const requireBinding = content.match(/(?:const|let|var)\s*{([^}]*)}\s*=\s*require\s*\(\s*["']@cloudflare\/vite-plugin["']\s*\)/)?.[1];
+		if (requireBinding) {
+			const requireMatch = requireBinding.match(/(?:^|,)\s*cloudflare\s*(?::\s*([A-Za-z_$][\w$]*))?\s*(?:,|$)/);
+			if (requireMatch) {
+				const binding = requireMatch[1] ?? "cloudflare";
+				return new RegExp(`\\b${escapeRegExp(binding)}\\s*\\(`).test(content);
+			}
+		}
+		const namedImports = content.match(/import\s*{([^}]*)}\s*from\s*["']@cloudflare\/vite-plugin["']/)?.[1];
+		if (!namedImports) return false;
+		const importMatch = namedImports.match(/(?:^|,)\s*cloudflare\s*(?:as\s+([A-Za-z_$][\w$]*))?\s*(?:,|$)/);
+		if (!importMatch) return false;
+		const binding = importMatch[1] ?? "cloudflare";
+		return new RegExp(`\\b${escapeRegExp(binding)}\\s*\\(`).test(content);
+	} catch {
+		return false;
+	}
+}
+/**
+* Extract the object-literal text of the `cache:` key (the `{ ... }` passed as
+* `vinext({ cache })`) from a Vite config source, via brace matching. Returns
+* null if there is no `cache:` object literal.
+*/
+function extractCacheBlock(content) {
+	const m = /\bcache\s*:\s*\{/.exec(content);
+	if (!m) return null;
+	const open = m.index + m[0].length - 1;
+	let depth = 0;
+	for (let i = open; i < content.length; i++) {
+		const ch = content[i];
+		if (ch === "{") depth++;
+		else if (ch === "}" && --depth === 0) return content.slice(open, i + 1);
+	}
+	return null;
+}
+/**
+* Whether a `cdn` / `data` field inside the cache object is assigned a real
+* value (not absent, `undefined`, or `null`). Reads the value up to the next
+* comma / closing brace / newline, which is enough to tell an assignment like
+* `data: kvDataAdapter()` from `data: undefined`.
+*/
+function cacheFieldAssigned(cacheBlock, field) {
+	const m = new RegExp(`\\b${field}\\s*:\\s*([^,}\\n]+)`).exec(cacheBlock);
+	if (!m) return false;
+	const value = m[1].trim();
+	return value.length > 0 && value !== "undefined" && value !== "null";
+}
+/**
+* Detect whether the Vite config assigns a CDN or data cache adapter — i.e. the
+* `cdn` or `data` field of the `vinext({ cache })` option is given a value.
+* This is a source-level check on those exact object fields, not a fuzzy scan
+* for adapter names. Mirrors {@link viteConfigHasCloudflarePlugin}'s leniency:
+* an unreadable or absent config is treated as configured so a deploy is never
+* blocked on a false negative.
+*/
+function viteConfigHasCacheAdapter(root) {
+	const configPath = findViteConfigPath(root);
+	if (!configPath) return true;
+	let content;
+	try {
+		content = fs.readFileSync(configPath, "utf-8");
+	} catch {
+		return true;
+	}
+	const block = extractCacheBlock(content);
+	if (!block) return false;
+	return cacheFieldAssigned(block, "cdn") || cacheFieldAssigned(block, "data");
+}
+function viteConfigHasImageAdapter(root) {
+	const configPath = findViteConfigPath(root);
+	if (!configPath) return true;
+	try {
+		const content = fs.readFileSync(configPath, "utf-8");
+		const match = /\bimages\s*:\s*\{/.exec(content);
+		if (!match) return false;
+		const open = match.index + match[0].length - 1;
+		let depth = 0;
+		for (let index = open; index < content.length; index++) if (content[index] === "{") depth++;
+		else if (content[index] === "}" && --depth === 0) {
+			const optimizer = /\boptimizer\s*:\s*([^,}\n]+)/.exec(content.slice(open, index + 1))?.[1];
+			return Boolean(optimizer && !/^(?:undefined|null)$/.test(optimizer.trim()));
+		}
+		return false;
+	} catch {
+		return true;
+	}
+}
+/**
+* Detect whether an existing user-authored Worker entry wires up a cache
+* backend imperatively via one of the `setCacheHandler` / `setDataCacheHandler`
+* / `setCdnCacheAdapter` setters. These setters are deprecated in favour of the
+* declarative `vinext({ cache })` option, but older apps that scaffolded a KV
+* cache handler into their Worker entry must keep working — so a deploy should
+* not be blocked when the Worker entry already configures a backend.
+*
+* This is a heuristic text scan (it doesn't execute the entry), mirroring
+* {@link viteConfigHasCacheAdapter}'s leniency: an unreadable Worker entry is
+* treated as configured so a deploy is never blocked on a false negative. A
+* missing Worker entry returns false (nothing to inspect — defer to other
+* checks).
+*/
+function workerEntryHasCacheHandler(root) {
+	const candidates = [path.join(root, "worker", "index.ts"), path.join(root, "worker", "index.js")];
+	for (const candidate of candidates) {
+		if (!fs.existsSync(candidate)) continue;
+		let content;
+		try {
+			content = fs.readFileSync(candidate, "utf-8");
+		} catch {
+			return true;
+		}
+		return /\b(?:setCacheHandler|setDataCacheHandler|setCdnCacheAdapter)\s*\(/.test(content);
+	}
+	return false;
+}
+/**
+* Build the error thrown when an ISR/cached app is deployed without a cache
+* adapter configured in the Vite config. Production deployments need a
+* persistent cache backend; vinext no longer scaffolds one into the Worker
+* entry, so it must be declared via `vinext({ cache })`.
+*/
+function formatMissingCacheAdapterError(options) {
+	const configRef = options.configFile ? options.configFile : "your Vite config";
+	return `[vinext] This app uses ISR / caching but no cache adapter is configured in ${configRef}.\n\n  Production deployments need a persistent cache backend. Declare one on the\n  vinext() plugin in ${configRef}:\n\n    import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";\n\n    export default defineConfig({\n      plugins: [\n        vinext({\n          cache: {\n            data: kvDataAdapter(), // KV-backed data cache (binding: VINEXT_KV_CACHE)\n          },\n        }),\n        cloudflare(),\n      ],\n    });\n\n  The VINEXT_KV_CACHE namespace binding is added to wrangler.jsonc for you.\n  Create the namespace with:\n\n    npx wrangler kv namespace create VINEXT_KV_CACHE`;
+}
+function formatImageOptimizationHint() {
+	return "  [vinext] next/image is served unoptimized. To enable edge image\n  optimization via Cloudflare Images, run:\n\n    vinext init --platform=cloudflare --image-optimization=cloudflare-images\n\n  This adds the imagesOptimizer() option to your Vite config and the matching\n  IMAGES binding to your Wrangler config without replacing existing settings.";
+}
+//#endregion
+export { formatImageOptimizationHint, formatMissingCacheAdapterError, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler };

package/dist/deploy-help.d.ts

@@ -0,0 +1,5 @@
+//#region src/deploy-help.d.ts
+declare function formatDeployHelp(): string;
+declare function printDeployHelp(): void;
+//#endregion
+export { formatDeployHelp, printDeployHelp };

package/dist/deploy-help.js

@@ -0,0 +1,55 @@
+//#region src/deploy-help.ts
+function formatDeployHelp() {
+	return `
+  vinext-cloudflare deploy - Deploy to Cloudflare Workers
+
+  Usage: vinext-cloudflare deploy [options]
+
+  One-command deployment to Cloudflare Workers. Automatically:
+    - Detects App Router or Pages Router
+    - Validates setup from vinext init --platform=cloudflare
+    - Builds the project with Vite
+    - Deploys via wrangler
+
+  Options:
+    --preview                Deploy to preview environment (same as --env preview)
+    --env <name>             Deploy using wrangler env.<name>
+    --name <name>            Custom Worker name (default: from package.json)
+    --skip-build             Skip the build step (use existing dist/)
+    --dry-run                Validate setup without building or deploying
+    --prerender-all          Pre-render discovered routes after building (future
+                             releases will auto-populate the remote cache)
+    --prerender-concurrency <count>
+                             Maximum number of routes to pre-render in parallel
+    -h, --help               Show this help
+
+  Experimental:
+    --experimental-tpr               Enable Traffic-aware Pre-Rendering
+    --tpr-coverage <pct>             Traffic coverage target, 0-100 (default: 90)
+    --tpr-limit <count>              Hard cap on pages to pre-render (default: 1000)
+    --tpr-window <hours>             Analytics lookback window in hours (default: 24)
+
+  TPR (Traffic-aware Pre-Rendering) uses Cloudflare zone analytics to determine
+  which pages get the most traffic and pre-renders them into KV cache during
+  deploy. This feature is experimental and must be explicitly enabled. Requires
+  a custom domain (zone analytics are unavailable on *.workers.dev) and the
+  CLOUDFLARE_API_TOKEN environment variable with Zone.Analytics read permission.
+
+  Examples:
+    npx @vinext/cloudflare deploy                                      Build and deploy to production
+    vpx @vinext/cloudflare deploy                                      Build and deploy with Vite+
+    vp exec vinext-cloudflare deploy                                   Run the locally installed Vite+ bin
+    vinext-cloudflare deploy --preview                                 Deploy to a preview URL
+    vinext-cloudflare deploy --env staging                             Deploy using wrangler env.staging
+    vinext-cloudflare deploy --dry-run                                 Validate setup without building or deploying
+    vinext-cloudflare deploy --name my-app                             Deploy with a custom Worker name
+    vinext-cloudflare deploy --experimental-tpr                        Enable TPR during deploy
+    vinext-cloudflare deploy --experimental-tpr --tpr-coverage 95      Cover 95% of traffic
+    vinext-cloudflare deploy --experimental-tpr --tpr-limit 500        Cap at 500 pages
+`;
+}
+function printDeployHelp() {
+	console.log(formatDeployHelp());
+}
+//#endregion
+export { formatDeployHelp, printDeployHelp };

package/dist/deploy.d.ts

@@ -0,0 +1,70 @@
+import { execFileSync } from "node:child_process";
+
+//#region src/deploy.d.ts
+type DeployOptions = {
+  /** Project root directory */root: string; /** Deploy to preview environment (default: production) */
+  preview?: boolean; /** Wrangler environment name from wrangler.jsonc env.<name> */
+  env?: string; /** Custom project name for the Worker */
+  name?: string; /** Skip the build step (assume already built) */
+  skipBuild?: boolean; /** Dry run — validate setup but don't build or deploy */
+  dryRun?: boolean; /** Pre-render all discovered routes into the dist output after building */
+  prerenderAll?: boolean; /** Maximum number of routes to prerender in parallel */
+  prerenderConcurrency?: number; /** Enable experimental TPR (Traffic-aware Pre-Rendering) */
+  experimentalTPR?: boolean; /** TPR: traffic coverage percentage target (0–100, default: 90) */
+  tprCoverage?: number; /** TPR: hard cap on number of pages to pre-render (default: 1000) */
+  tprLimit?: number; /** TPR: analytics lookback window in hours (default: 24) */
+  tprWindow?: number;
+};
+declare function parseDeployArgs(args: string[]): {
+  help: boolean;
+  preview: boolean;
+  env: string | undefined;
+  name: string | undefined;
+  skipBuild: boolean;
+  dryRun: boolean;
+  prerenderAll: boolean;
+  prerenderConcurrency: number | undefined;
+  experimentalTPR: boolean;
+  tprCoverage: number | undefined;
+  tprLimit: number | undefined;
+  tprWindow: number | undefined;
+};
+/**
+ * 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.
+ */
+declare function withCloudflareEnv<T>(env: string | undefined, fn: () => Promise<T>): Promise<T>;
+type WranglerDeployArgs = {
+  args: string[];
+  env: string | undefined;
+};
+declare function validateWranglerEnvName(env: string): string;
+declare function buildWranglerDeployArgs(options: Pick<DeployOptions, "preview" | "env">): WranglerDeployArgs;
+/**
+ * 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.
+ */
+declare function resolveWranglerBin(root: string, resolvePackageJson?: (root: string) => string | null): string;
+declare function buildNodeCliInvocation(scriptPath: string, args: string[], nodeExecutable?: string): {
+  file: string;
+  args: string[];
+};
+declare function buildWranglerInvocation(root: string, options: Pick<DeployOptions, "preview" | "env">, nodeExecutable?: string): {
+  file: string;
+  args: string[];
+  env: string | undefined;
+};
+declare function runWranglerDeploy(root: string, options: Pick<DeployOptions, "preview" | "env">, execute?: typeof execFileSync): string;
+declare function deploy(options: DeployOptions): Promise<void>;
+//#endregion
+export { DeployOptions, buildNodeCliInvocation, buildWranglerDeployArgs, buildWranglerInvocation, deploy, parseDeployArgs, resolveWranglerBin, runWranglerDeploy, validateWranglerEnvName, withCloudflareEnv };