@vinext/cloudflare 1.1.1 → 1.2.1

package/dist/cache/cdn-adapter-config.d.ts

@@ -28,4 +28,5 @@ export declare function finalizeCdnAdapterBuildOutput({ root, outDir, isPrimaryS
   binding: string;
   bindingIsExplicit: boolean;
 }): Promise<void>;
-//#endregion
+//#endregion
+export {};

package/dist/cache/cdn-adapter.runtime.js

@@ -132,6 +132,7 @@ function toEdgeCacheControl(cacheControl) {
 */
 const MAX_CACHE_TAG_BYTES = 16384;
 const CACHE_TAG_PREFIX = "vinext-";
+const MAX_TAGS_PER_PURGE = 100;
 /** Encode a case-sensitive Next.js tag into a fixed Workers Cache tag. */
 function encodeCloudflareCacheTag(tag) {
 	return `${CACHE_TAG_PREFIX}${fnv1a64(`0:${tag}`)}${fnv1a64(`1:${tag}`)}`;
@@ -222,11 +223,16 @@ var CloudflareCdnCacheAdapter = class {
 		if (!cache) return;
 		const tagList = (Array.isArray(tags) ? tags : [tags]).filter((t) => typeof t === "string");
 		if (tagList.length === 0) return;
-		const options = { tags: tagList.map(encodeCloudflareCacheTag) };
+		const encodedTags = [...new Set(tagList.map(encodeCloudflareCacheTag))];
 		const operation = isStaleTagInvalidation(durations) ? "invalidate" : "purge";
-		const result = await (operation === "invalidate" ? invalidateOrPurge(cache, options) : cache.purge(options));
-		if (result?.success === false) {
-			const errors = result.errors.map(({ code, message }) => `${code}: ${message}`).join(", ");
+		const chunks = [];
+		for (let i = 0; i < encodedTags.length; i += MAX_TAGS_PER_PURGE) chunks.push(encodedTags.slice(i, i + MAX_TAGS_PER_PURGE));
+		const settled = await Promise.allSettled(chunks.map(async (chunk) => await (operation === "invalidate" ? invalidateOrPurge(cache, { tags: chunk }) : cache.purge({ tags: chunk }))));
+		const rejection = settled.find((result) => result.status === "rejected");
+		if (rejection) throw rejection.reason;
+		const failures = settled.flatMap((result) => result.status === "fulfilled" && result.value?.success === false ? [result.value] : []);
+		if (failures.length > 0) {
+			const errors = failures.flatMap((result) => result.errors).map(({ code, message }) => `${code}: ${message}`).join(", ");
 			throw new Error(`[vinext] Workers Cache ${operation} failed${errors ? `: ${errors}` : ""}`);
 		}
 	}

package/dist/cache/cdn-adapter.worker.js

@@ -132,7 +132,8 @@ async function createCacheFacingRequest(request, serializedInvocation) {
 	return new Request(url, {
 		cf: { vary: { default: { action: "passthrough" } } },
 		headers,
-		method: request.method
+		method: request.method,
+		redirect: "manual"
 	});
 }
 function restoreResponseStageRequest(request, requestUrl, requestMethod) {

package/dist/cache/config.d.ts

@@ -134,4 +134,5 @@ export declare function createWorkersCacheConfig({ versionMetadataBinding }?: {
     VinextUncachedResponse: import("cf/config").WorkerEntrypointExport;
   };
 }>;
-//#endregion
+//#endregion
+export {};

package/dist/cache/kv-data-adapter.runtime.d.ts

@@ -60,7 +60,7 @@ export declare class KVCacheHandler implements CacheHandler {
   private keySpace;
   private ctx;
   private ttlSeconds;
-  /** Local in-memory cache for tag invalidation timestamps. Avoids redundant KV reads. */
+  /** Local in-memory cache for tag invalidation markers. Avoids redundant KV reads. */
   private _tagCache;
   /** Monotonic ordering for concurrent tag-cache fills and local invalidations. */
   private _tagCacheOrder;
@@ -95,14 +95,18 @@ export declare class KVCacheHandler implements CacheHandler {
    */
   private _readTagMarkers;
   /**
-   * Report whether any tag has an invalidation marker at or after `lastModified`.
+   * Report whether any tag expired an entry last modified at `lastModified`:
+   * its marker's expire time is at or after `lastModified` and, for a cacheLife
+   * profile's marker, has passed.
    * Call `_primeTagCache` for the same tags first — a tag with no cache entry
    * counts as never invalidated. Pass `requireFresh` to call it before a prime,
    * so an entry past `tagCacheTtlMs` does not answer for a tag it never re-read.
    */
   private _hasRevalidatedTag;
+  /** Report whether any primed tag was marked stale after `lastModified`. */
+  private _hasStaleTag;
   set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
-  revalidateTag(tags: string | string[], _durations?: {
+  revalidateTag(tags: string | string[], durations?: {
     expire?: number;
   }): Promise<void>;
   /**

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

@@ -1,3 +1,4 @@
+import { isStaleTagInvalidation } from "./workers-cache-invalidation.js";
 import { isUnknownRecord, readCacheControlNumberField } from "../utils/cache-control-metadata.js";
 import { ENTRY_PREFIX, createKvKeySpace, resolveKvExpirationTtlSeconds } from "./kv-key.js";
 import { Buffer } from "node:buffer";
@@ -24,6 +25,23 @@ import { getRequestExecutionContext } from "vinext/shims/request-context";
 */
 /** Default KV namespace binding name read from the Worker `env`. */
 const DEFAULT_BINDING = "VINEXT_KV_CACHE";
+function parseTagMarker(raw) {
+	if (raw === null || raw === void 0) return {};
+	if (!raw.startsWith("{")) return { expired: /^\d+$/.test(raw) ? Number(raw) : NaN };
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return { expired: NaN };
+	}
+	if (!isUnknownRecord(parsed)) return { expired: NaN };
+	const { stale, expired } = parsed;
+	if (stale === void 0 && expired === void 0 || stale !== void 0 && typeof stale !== "number" || expired !== void 0 && typeof expired !== "number") return { expired: NaN };
+	return {
+		...stale === void 0 ? {} : { stale },
+		...expired === void 0 ? {} : { expired }
+	};
+}
 /** Prefix used by revalidatePath for path-based tags. */
 const PATH_TAG_PREFIX = "_N_T_";
 /** The runtime rejects a lower `cacheTtl` with "Cache TTL must be at least 30". */
@@ -98,7 +116,7 @@ var KVCacheHandler = class {
 	keySpace;
 	ctx;
 	ttlSeconds;
-	/** Local in-memory cache for tag invalidation timestamps. Avoids redundant KV reads. */
+	/** Local in-memory cache for tag invalidation markers. Avoids redundant KV reads. */
 	_tagCache = /* @__PURE__ */ new Map();
 	/** Monotonic ordering for concurrent tag-cache fills and local invalidations. */
 	_tagCacheOrder = 0;
@@ -179,6 +197,7 @@ var KVCacheHandler = class {
 			return null;
 		}
 		if (this._hasRevalidatedTag(softTags, entry.lastModified)) return null;
+		const hasStaleTag = this._hasStaleTag([...entryTags, ...softTags], entry.lastModified);
 		if (entry.expireAt !== void 0 && entry.expireAt !== null && Date.now() > entry.expireAt) {
 			this._deleteEntryReadInBackground(kvKey);
 			return null;
@@ -186,7 +205,7 @@ var KVCacheHandler = class {
 		const now = Date.now();
 		const requestedRevalidate = readPositiveNumberField(_ctx, "revalidate");
 		const requestedRevalidateAt = requestedRevalidate === void 0 ? null : entry.lastModified + requestedRevalidate * 1e3;
-		if (entry.revalidateAt !== null && now > entry.revalidateAt || requestedRevalidateAt !== null && now > requestedRevalidateAt) return {
+		if (hasStaleTag || entry.revalidateAt !== null && now > entry.revalidateAt || requestedRevalidateAt !== null && now > requestedRevalidateAt) return {
 			lastModified: entry.lastModified,
 			value: restoredValue,
 			cacheState: "stale",
@@ -221,7 +240,7 @@ var KVCacheHandler = class {
 			if (current && current.order >= order) continue;
 			const marker = markers.get(this._tagKey(tag));
 			tagCache.set(tag, {
-				timestamp: marker ? Number(marker) : 0,
+				marker: parseTagMarker(marker),
 				fetchedAt: now,
 				order
 			});
@@ -244,18 +263,30 @@ var KVCacheHandler = class {
 		return markers;
 	}
 	/**
-	* Report whether any tag has an invalidation marker at or after `lastModified`.
+	* Report whether any tag expired an entry last modified at `lastModified`:
+	* its marker's expire time is at or after `lastModified` and, for a cacheLife
+	* profile's marker, has passed.
 	* Call `_primeTagCache` for the same tags first — a tag with no cache entry
 	* counts as never invalidated. Pass `requireFresh` to call it before a prime,
 	* so an entry past `tagCacheTtlMs` does not answer for a tag it never re-read.
 	*/
 	_hasRevalidatedTag(tags, lastModified, requireFresh = false) {
-		const now = requireFresh ? Date.now() : 0;
+		const now = Date.now();
 		for (const tag of tags) {
 			const cached = this._tagCache.get(tag);
-			if (!cached || cached.timestamp === 0) continue;
+			if (cached?.marker.expired === void 0) continue;
 			if (requireFresh && now - cached.fetchedAt >= this._tagCacheTtl) continue;
-			if (Number.isNaN(cached.timestamp) || cached.timestamp >= lastModified) return true;
+			const { stale, expired } = cached.marker;
+			const pending = stale !== void 0 && expired > now;
+			if (Number.isNaN(expired) || expired >= lastModified && !pending) return true;
+		}
+		return false;
+	}
+	/** Report whether any primed tag was marked stale after `lastModified`. */
+	_hasStaleTag(tags, lastModified) {
+		for (const tag of tags) {
+			const stale = this._tagCache.get(tag)?.marker.stale;
+			if (stale !== void 0 && stale > lastModified) return true;
 		}
 		return false;
 	}
@@ -300,16 +331,32 @@ var KVCacheHandler = class {
 			metadata
 		});
 	}
-	async revalidateTag(tags, _durations) {
+	async revalidateTag(tags, durations) {
 		const tagList = Array.isArray(tags) ? tags : [tags];
 		const now = Date.now();
 		const validTags = tagList.filter((t) => validateTag(t) !== null);
-		await Promise.all(validTags.map((tag) => this.kv.put(this._tagKey(tag), String(now))));
+		const markers = await Promise.all(validTags.map(async (tag) => {
+			const tagKey = this._tagKey(tag);
+			if (!isStaleTagInvalidation(durations)) {
+				await this.kv.put(tagKey, String(now));
+				return { expired: now };
+			}
+			const expire = durations?.expire;
+			const expired = expire === void 0 ? parseTagMarker(await this.kv.get(tagKey)).expired : now + expire * 1e3;
+			const marker = {
+				stale: now,
+				...expired !== void 0 && Number.isFinite(expired) ? { expired } : {}
+			};
+			await this.kv.put(tagKey, JSON.stringify(marker));
+			return marker;
+		}));
 		const order = ++this._tagCacheOrder;
-		for (const tag of validTags) this._tagCache.set(tag, {
-			timestamp: now,
-			fetchedAt: now,
-			order
+		validTags.forEach((tag, index) => {
+			this._tagCache.set(tag, {
+				marker: markers[index],
+				fetchedAt: now,
+				order
+			});
 		});
 	}
 	/**

package/dist/cache/response-store-adapter.worker.d.ts

@@ -11,4 +11,5 @@ export declare function createVinextResponseStoreOptions<Env extends VinextRespo
 export declare function createVinextResponseStoreHandler(store: WorkersResponseStore): {
   fetch(request: Request, env: VinextResponseStoreEnv, ctx: WorkerExecutionContext): Promise<Response>;
 };
-//#endregion
+//#endregion
+export {};

package/dist/cache/response-store-data.runtime.js

@@ -6,10 +6,11 @@ import { cacheForRequest } from "vinext/cache";
 //#region src/cache/response-store-data.runtime.ts
 const ARRAY_BUFFER_MARKER = "$vinextArrayBuffer";
 const CACHE_MAX_AGE_SECONDS = 31536e4;
-const CACHE_MAX_AGE = `public, max-age=${CACHE_MAX_AGE_SECONDS}`;
 const DATA_ENTRY_PATH = "__vinext_data";
 const REPLAYABLE_HEADER = "X-Vinext-Response-Store-Replayable";
 const MAX_CACHE_TAG_HEADER_BYTES = 16384;
+/** How long past its revalidate a current Store's hit can still be marked fresh: write latency. */
+const STALE_FRESH_HIT_GRACE_MS = 5e3;
 const DATA_REVALIDATOR_ID = "vinext:data";
 const CACHE_FUNCTION_REVALIDATOR_ID = "vinext:cache-function";
 const invocationStorage = new AsyncLocalStorage();
@@ -194,9 +195,9 @@ function deserialize(value) {
 	return entry;
 }
 function cachePolicy(revalidate, expire) {
-	if (revalidate === false || revalidate === void 0) return `public, max-age=${CACHE_MAX_AGE_SECONDS}`;
-	const staleSeconds = expire === void 0 ? CACHE_MAX_AGE_SECONDS : Math.max(0, expire - revalidate);
-	return `public, max-age=${Math.max(0, revalidate)}, stale-while-revalidate=${staleSeconds}`;
+	if (revalidate === false || revalidate === void 0) return `public, max-age=${expire === void 0 ? CACHE_MAX_AGE_SECONDS : Math.max(1, Math.ceil(expire))}`;
+	const maxAge = revalidate > 0 ? Math.max(1, Math.floor(revalidate)) : 0;
+	return `public, max-age=${maxAge}, stale-while-revalidate=${expire === void 0 ? CACHE_MAX_AGE_SECONDS : Math.max(0, Math.ceil(expire) - maxAge)}`;
 }
 var WorkersResponseStoreCacheHandler = class {
 	store;
@@ -244,12 +245,13 @@ var WorkersResponseStoreCacheHandler = class {
 			}
 			const age = Date.now() - entry.lastModified;
 			const requestedRevalidate = readCacheControlField(context, "revalidate");
+			const storedRevalidate = entry.cacheControl?.revalidate;
 			const requestedStale = typeof requestedRevalidate === "number" && requestedRevalidate > 0 && age > requestedRevalidate * 1e3;
 			let cacheState;
 			if (response.headers.get(REPLAYABLE_HEADER) === "1") {
 				if (requestedStale && storeStatus !== "BLOB-STALE") cacheState = "stale";
 			} else if (typeof entry.cacheControl?.expire === "number" && age > entry.cacheControl.expire * 1e3) cacheState = "expired";
-			else if (requestedStale || storeStatus === "BLOB-STALE" || typeof entry.cacheControl?.revalidate === "number" && entry.cacheControl.revalidate > 0 && age > entry.cacheControl.revalidate * 1e3) cacheState = "stale";
+			else if (storeStatus === "BLOB-STALE" || requestedStale && typeof requestedRevalidate === "number" && (typeof storedRevalidate !== "number" || requestedRevalidate < storedRevalidate) || typeof storedRevalidate === "number" && storedRevalidate > 0 && age > storedRevalidate * 1e3 + STALE_FRESH_HIT_GRACE_MS) cacheState = "stale";
 			return {
 				lastModified: entry.lastModified,
 				value: entry.value,
@@ -274,9 +276,11 @@ var WorkersResponseStoreCacheHandler = class {
 		let revalidate = readCacheControlField(context, "revalidate");
 		if (value && "revalidate" in value) revalidate = value.revalidate;
 		if (revalidate === 0) return;
+		if (typeof revalidate === "number" && !Number.isFinite(revalidate)) revalidate = false;
 		const rawExpire = readCacheControlField(context, "expire");
-		const expire = typeof rawExpire === "number" ? rawExpire : void 0;
-		const stale = readCacheControlField(context, "stale");
+		const expire = typeof rawExpire === "number" && Number.isFinite(rawExpire) ? rawExpire : void 0;
+		const rawStale = readCacheControlField(context, "stale");
+		const stale = typeof rawStale === "number" && Number.isFinite(rawStale) ? rawStale : void 0;
 		const cacheControl = typeof revalidate === "number" || revalidate === false ? {
 			revalidate,
 			...typeof expire === "number" ? { expire } : {},
@@ -303,7 +307,7 @@ var WorkersResponseStoreCacheHandler = class {
 			lastModified: Date.now(),
 			value
 		}), { headers: {
-			"Cache-Control": revalidator ? cachePolicy(revalidate, expire) : CACHE_MAX_AGE,
+			"Cache-Control": cachePolicy(revalidate, expire),
 			...tagHeader ? { "Cache-Tag": tagHeader } : {},
 			"Content-Type": "application/json",
 			...revalidator ? { [REPLAYABLE_HEADER]: "1" } : {}

package/dist/cache/static-assets-adapter.runtime.d.ts

@@ -26,4 +26,5 @@ export default function createStaticAssetsCacheAdapter({ env, options }?: {
   env?: Record<string, unknown>;
   options?: StaticAssetsAdapterOptions;
 }): CdnCacheAdapter;
-//#endregion
+//#endregion
+export {};

package/dist/cache/workers-cache-invalidation.d.ts

@@ -27,4 +27,5 @@ export declare function hasCacheMethod<Name extends CacheMethodName>(value: unkn
  * `undefined` when the cache supports neither.
  */
 export declare function invalidateOrPurge(cache: unknown, options: CacheInvalidationOptions): unknown;
-//#endregion
+//#endregion
+export {};

package/dist/cdn-warm.d.ts

@@ -130,4 +130,5 @@ export declare function waitForCdnWarmTargetReadiness(options: Pick<CdnWarmOptio
 }): Promise<CdnWarmReadinessResult>;
 export declare function warmCdnCache(options: CdnWarmOptions): Promise<CdnWarmResult>;
 export declare function warmCdnCacheFromPrerender(options: PrerenderCdnWarmOptions): Promise<CdnWarmResult>;
-//#endregion
+//#endregion
+export {};

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { deploy, parseDeployArgs } from "./deploy.js";
-import { printDeployHelp } from "./deploy-help.js";
+import { printDeployHelp, printPreviewsDeployHelp } from "./deploy-help.js";
+import { parsePreviewsDeployArgs } from "./previews-deploy.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;
@@ -11,6 +12,10 @@ function printHelp(commandName) {
 		printDeployHelp();
 		return;
 	}
+	if (commandName === "previews") {
+		printPreviewsDeployHelp();
+		return;
+	}
 	console.log(`
   vinext-cloudflare v${VERSION}
 
@@ -21,7 +26,8 @@ function printHelp(commandName) {
     vp exec vinext-cloudflare <command>    Run the locally installed bin
 
   Commands:
-    deploy   Deploy to Cloudflare Workers
+    deploy                          Deploy to Cloudflare Workers
+    previews deploy [preview-name]  Deploy a Cloudflare Worker Preview
 
   Options:
     -h, --help     Show this help
@@ -68,6 +74,30 @@ async function deployCommand() {
 		tprWindow: parsed.tprWindow
 	});
 }
+async function previewsCommand() {
+	const subcommand = rawArgs[0];
+	if (subcommand !== "deploy") {
+		if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+			printHelp("previews");
+			return;
+		}
+		throw new Error(`Unknown previews command: ${subcommand}`);
+	}
+	const options = parsePreviewsDeployArgs(rawArgs.slice(1));
+	if (options.help) {
+		printHelp("previews");
+		return;
+	}
+	await deploy({
+		root: process.cwd(),
+		env: options.mode,
+		skipBuild: options.skipBuild,
+		target: {
+			type: "preview",
+			name: options.name
+		}
+	});
+}
 if (command === "--version" || command === "-v") {
 	console.log(`vinext-cloudflare v${VERSION}`);
 	process.exit(0);
@@ -83,6 +113,12 @@ switch (command) {
 			process.exit(1);
 		});
 		break;
+	case "previews":
+		previewsCommand().catch((error) => {
+			console.error(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		});
+		break;
 	default:
 		console.error(`Unknown command: ${command}`);
 		printHelp();

package/dist/deploy-help.d.ts

@@ -1,4 +1,6 @@
 //#region src/deploy-help.d.ts
 export declare function formatDeployHelp(): string;
 export declare function printDeployHelp(): void;
+export declare function formatPreviewsDeployHelp(): string;
+export declare function printPreviewsDeployHelp(): void;
 //#endregion

package/dist/deploy-help.js

@@ -87,11 +87,14 @@ function formatDeployHelp() {
   be reused outside the data center reached by the warmup request after cache
   propagation, but the deploy does not wait for every edge location to fill.
 
+  --preview is an alias for --env preview. It selects a mode/environment,
+  not a Preview deployment. Use previews deploy to deploy a Worker Preview.
+
   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 --preview                                 Deploy using mode/environment preview
     vinext-cloudflare deploy --env staging                             Deploy using Cloudflare mode/environment staging
     vinext-cloudflare deploy --config dist/server/wrangler.json        Deploy using a generated Wrangler config
     vinext-cloudflare deploy --dry-run                                 Validate setup without building or deploying
@@ -113,5 +116,32 @@ function formatDeployHelp() {
 function printDeployHelp() {
 	console.log(formatDeployHelp());
 }
+function formatPreviewsDeployHelp() {
+	return `
+  vinext-cloudflare previews deploy - Deploy a Cloudflare Worker Preview
+
+  Usage: vinext-cloudflare previews deploy [preview-name] [options]
+
+  Builds the app with isPreview=true, then deploys its Preview Build Output
+  using cf previews deploy. Requires cloudflare.config.ts and the cf CLI.
+
+  Arguments:
+    preview-name    Optional Preview name (cf uses the CI or Git branch if omitted)
+
+  Options:
+    --mode <mode>   Vite mode to build and deploy in (default: production)
+    --skip-build    Deploy existing Preview Build Output without rebuilding
+    -h, --help      Show this help
+
+  Examples:
+    vinext-cloudflare previews deploy
+    vinext-cloudflare previews deploy pr-123
+    vinext-cloudflare previews deploy pr-123 --mode staging
+    vinext-cloudflare previews deploy pr-123 --skip-build
+`;
+}
+function printPreviewsDeployHelp() {
+	console.log(formatPreviewsDeployHelp());
+}
 //#endregion
-export { formatDeployHelp, printDeployHelp };
+export { formatDeployHelp, formatPreviewsDeployHelp, printDeployHelp, printPreviewsDeployHelp };

package/dist/deploy.d.ts

@@ -12,6 +12,11 @@ export type DeployOptions = {
   root: string;
   /** Deploy to preview environment (default: production) */
   preview?: boolean;
+  /** Deploy to Preview deployment, supported only by cf. */
+  target?: {
+    type: "preview";
+    name?: string;
+  };
   /** Wrangler environment name from wrangler.jsonc env.<name> */
   env?: string;
   /** Custom project name for the Worker */
@@ -120,6 +125,8 @@ export declare function parseDeployArgs(args: string[]): {
  * Passing `undefined` is a no-op; the callback runs with `process.env` untouched.
  */
 export declare function withCloudflareEnv<T>(env: string | undefined, fn: () => Promise<T>): Promise<T>;
+/** Cloudflare Vite Plugin reads this flag when evaluating the typed config and emitting Build Output. */
+export declare function withCloudflarePreviewBuild<T>(fn: () => Promise<T>): Promise<T>;
 export declare function resolveViteBuildMode(deploymentTool: DeploymentTool, env: string | undefined): string;
 type WranglerDeployArgs = {
   args: string[];
@@ -133,7 +140,7 @@ export declare function validateWranglerEnvName(env: string): string;
 export declare function buildWranglerDeployArgs(options: Pick<DeployOptions, "preview" | "env" | "name" | "config">): WranglerDeployArgs;
 export declare function resolveDeploymentTool(root: string): DeploymentTool;
 export declare function isCfCliInstalled(root: string, resolvePackageJson?: (root: string) => string | null): boolean;
-export declare function buildCfDeployArgs(options: Pick<DeployOptions, "preview" | "env">): CfDeployArgs;
+export declare function buildCfDeployArgs(options: Pick<DeployOptions, "preview" | "env" | "target">): CfDeployArgs;
 /**
  * Resolve Wrangler's JavaScript CLI entrypoint in node_modules.
  *
@@ -154,7 +161,7 @@ export declare function buildWranglerInvocation(root: string, options: Pick<Depl
 export declare function runWranglerDeploy(root: string, options: Pick<DeployOptions, "preview" | "env" | "name" | "config" | "verbose"> & {
   promote?: boolean;
 }, execute?: typeof spawn): Promise<string>;
-export declare function runCfDeploy(root: string, options: Pick<DeployOptions, "preview" | "env">, execute?: typeof spawn): Promise<string>;
+export declare function runCfDeploy(root: string, options: Pick<DeployOptions, "preview" | "env" | "target">, execute?: typeof spawn): Promise<string>;
 export declare function hasCdnWarmRequests(plan: Omit<CdnWarmRequestPlan, "pagesDataPaths"> & {
   pagesDataPaths?: readonly string[];
 }): boolean;
@@ -185,4 +192,5 @@ export declare function resolveDeploymentControlPlaneOptions(options: Deployment
 export declare function resolveWorkerNameForVersionOverride(config: ParsedWranglerConfig | null, options: Pick<DeployOptions, "preview" | "env" | "name">): string | undefined;
 export declare function buildVersionOverrideHeaders(workerName: string | undefined, versionId: string): HeadersInit | undefined;
 export declare function deploy(options: DeployOptions): Promise<void>;
-//#endregion
+//#endregion
+export {};

package/dist/deploy.js

@@ -16,7 +16,7 @@ import { setTimeout } from "node:timers/promises";
 import { DEFAULT_REMOTE_PATH_DISCOVERY_PHASE_TIMEOUT_MS, DEFAULT_REMOTE_PATH_DISCOVERY_RETRY_DELAY_MS, discoverPrerenderPathManifest, emitPrerenderPathManifest } from "vinext/internal/build/prerender-paths";
 import { normalizePathTrailingSlash } from "vinext/shims/url-utils";
 import { spawn } from "node:child_process";
-import { parseArgs } from "node:util";
+import { parseArgs, stripVTControlCharacters } from "node:util";
 import { pathToFileURL } from "node:url";
 import { VINEXT_BUILD_LIFECYCLE_CONFIG } from "vinext/internal/build/lifecycle";
 import { runPrerender } from "vinext/internal/build/run-prerender";
@@ -301,6 +301,18 @@ async function withCloudflareEnv(env, fn) {
 		else delete process.env.CLOUDFLARE_ENV;
 	}
 }
+/** Cloudflare Vite Plugin reads this flag when evaluating the typed config and emitting Build Output. */
+async function withCloudflarePreviewBuild(fn) {
+	const hadPrevious = "CLOUDFLARE_PREVIEW_BUILD" in process.env;
+	const previous = process.env.CLOUDFLARE_PREVIEW_BUILD;
+	process.env.CLOUDFLARE_PREVIEW_BUILD = "true";
+	try {
+		return await fn();
+	} finally {
+		if (hadPrevious) process.env.CLOUDFLARE_PREVIEW_BUILD = previous;
+		else delete process.env.CLOUDFLARE_PREVIEW_BUILD;
+	}
+}
 async function loadProjectViteApi(root) {
 	let vitePath;
 	try {
@@ -384,7 +396,10 @@ function isCfCliInstalled(root, resolvePackageJson = (projectRoot) => {
 }
 function buildCfDeployArgs(options) {
 	const mode = options.env || (options.preview ? "preview" : void 0);
-	const args = ["deploy", "--prebuilt"];
+	const isPreviewDeploy = options.target?.type === "preview";
+	const args = isPreviewDeploy ? ["previews", "deploy"] : ["deploy"];
+	if (isPreviewDeploy && options.target?.name) args.push(options.target.name);
+	args.push("--prebuilt");
 	if (mode) args.push("--mode", validateWranglerEnvName(mode));
 	return {
 		args,
@@ -482,7 +497,8 @@ async function runWranglerDeploy(root, options, execute = spawn) {
 }
 async function runCfDeploy(root, options, execute = spawn) {
 	const { args, mode } = buildCfDeployArgs(options);
-	console.log(mode ? `\n  Deploying Build Output in mode: ${mode}...` : "\n  Deploying Build Output...");
+	const isPreview = options.target?.type === "preview";
+	console.log(mode ? `\n  Deploying ${isPreview ? "Preview " : ""}Build Output in mode: ${mode}...` : "\n  Deploying Build Output...");
 	const child = execute(process.execPath, [resolveCfBin(root), ...args], {
 		cwd: root,
 		stdio: [
@@ -493,9 +509,11 @@ async function runCfDeploy(root, options, execute = spawn) {
 		shell: false
 	});
 	let output = "";
+	let stdout = "";
 	child.stdout?.on("data", (chunk) => {
 		const text = chunk.toString();
 		output += text;
+		stdout += text;
 		process.stdout.write(text);
 	});
 	child.stderr?.on("data", (chunk) => {
@@ -507,11 +525,27 @@ async function runCfDeploy(root, options, execute = spawn) {
 		child.once("error", reject);
 		child.once("close", (code, signal) => {
 			if (code === 0) resolve();
-			else reject(/* @__PURE__ */ new Error(`cf deploy failed with ${signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`}.`));
+			else reject(/* @__PURE__ */ new Error(`cf ${isPreview ? "previews deploy" : "deploy"} failed with ${signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`}.`));
 		});
 	});
+	if (isPreview) return parseCfPreviewUrl(stdout) ?? parseWorkerDeploymentUrl(output) ?? "(Preview URL not detected in cf output)";
 	return parseWorkerDeploymentUrl(output) ?? "(URL not detected in cf output)";
 }
+/** `cf previews deploy` prints a JSON result; prefer the named Preview URL over the deployment URL. */
+function parseCfPreviewUrl(stdout) {
+	const text = stripVTControlCharacters(stdout);
+	const start = text.indexOf("{");
+	const end = text.lastIndexOf("}");
+	if (start === -1 || end < start) return null;
+	let result;
+	try {
+		result = JSON.parse(text.slice(start, end + 1));
+	} catch {
+		return null;
+	}
+	for (const urls of [result.preview_urls, result.deployment_urls]) if (Array.isArray(urls) && typeof urls[0] === "string") return urls[0];
+	return null;
+}
 function hasCdnWarmRequests(plan) {
 	return plan.paths.length + (plan.pagesDataPaths?.length ?? 0) + (plan.routeHandlerPaths?.length ?? 0) + plan.rscPaths.length + plan.loadingShellPaths.length > 0;
 }
@@ -1130,21 +1164,41 @@ function withPromotedVersionWarmupNote(error) {
 	const message = error instanceof Error ? error.message : String(error);
 	return new Error(`${message} The uploaded version is already promoted to 100% and its Worker triggers/routes were updated; rerun deploy to retry cache warming or create a deployment for the previous version.`, { cause: error });
 }
+/** Worker Previews skip production-only steps, so reject options that would otherwise be ignored. */
+function assertPreviewDeployOptions(options) {
+	const unsupported = Object.entries({
+		preview: options.preview,
+		name: options.name !== void 0,
+		config: options.config !== void 0,
+		warmCdnCache: options.warmCdnCache,
+		warmCdnTarget: options.warmCdnTarget !== void 0,
+		warmCdnCertify: options.warmCdnCertify,
+		warmCdnPromote: options.warmCdnPromote === false,
+		experimentalTPR: options.experimentalTPR
+	}).filter(([, isSet]) => isSet).map(([option]) => option);
+	if (unsupported.length > 0) throw new Error(`Worker Preview deployments do not support: ${unsupported.join(", ")}.`);
+}
 async function deploy(options) {
+	const isPreview = options.target?.type === "preview";
+	if (isPreview) assertPreviewDeployOptions(options);
 	if (options.warmCdnTarget !== void 0 && !options.warmCdnCache && !options.experimentalTPR) throw new Error("--warm-cache-target requires --warm-cache or --traffic-aware-warm-cache.");
 	const warmCdnTarget = options.warmCdnTarget === void 0 ? void 0 : validateCdnWarmTarget(options.warmCdnTarget);
 	const deployEnv = options.env || (options.preview ? "preview" : void 0);
 	if (deployEnv) validateWranglerEnvName(deployEnv);
 	const root = path.resolve(options.root);
 	const deploymentTool = resolveDeploymentTool(root);
+	if (isPreview && deploymentTool !== "cf") throw new Error("Worker Previews require a cloudflare.config.ts project and the cf CLI.");
 	if (deploymentTool === "cf" && options.name) throw new Error("--name is not supported for cloudflare.config.ts projects. Set `name` in cloudflare.config.ts instead.");
 	const viteMode = resolveViteBuildMode(deploymentTool, deployEnv);
 	const wranglerFallbackEnv = deploymentTool === "cf" ? void 0 : deployEnv;
+	if (!process.env.NODE_ENV) Reflect.set(process.env, "NODE_ENV", "production");
 	loadDotenv({
 		root,
 		mode: viteMode
 	});
-	console.log("\n  vinext-cloudflare deploy\n");
+	const cloudflareEnv = isPreview ? void 0 : deployEnv;
+	const withBuildContext = (fn) => withCloudflareEnv(cloudflareEnv, () => isPreview ? withCloudflarePreviewBuild(fn) : fn());
+	console.log(isPreview ? "\n  vinext-cloudflare previews deploy\n" : "\n  vinext-cloudflare deploy\n");
 	const info = detectProject(root);
 	if (!info.isAppRouter && !info.isPagesRouter) {
 		console.error("  Error: No app/ or pages/ directory found.");
@@ -1171,9 +1225,17 @@ async function deploy(options) {
 		console.log("\n  Dry run complete. No build or deploy performed.\n");
 		return;
 	}
-	const viteConfigMetadata = await withCloudflareEnv(deployEnv, () => loadDeployViteConfigMetadata(info.root, viteMode));
+	if (isPreview && options.skipBuild) {
+		console.log("\n  Skipping build (--skip-build)");
+		printDeployUrl("Preview URL", await runCfDeploy(root, {
+			env: viteMode,
+			target: options.target
+		}));
+		return;
+	}
+	const viteConfigMetadata = await withBuildContext(() => loadDeployViteConfigMetadata(info.root, viteMode));
 	const cdnAdapterConfig = resolveCdnAdapterConfig(viteConfigMetadata.cacheConfig);
-	const nextConfig = await withCloudflareEnv(deployEnv, async () => {
+	const nextConfig = await withBuildContext(async () => {
 		const inlineNextConfig = viteConfigMetadata.nextConfig;
 		const rawNextConfig = inlineNextConfig ? await resolveNextConfigInput(inlineNextConfig, PHASE_PRODUCTION_BUILD) : await loadNextConfig(info.root, PHASE_PRODUCTION_BUILD);
 		return resolveNextConfig(rawNextConfig, info.root);
@@ -1194,10 +1256,10 @@ async function deploy(options) {
 	const shouldEmitPrerenderPathManifest = !options.skipBuild && shouldPrerenderLocally;
 	if (prerenderDecision && !shouldPrerenderLocally) {
 		const trigger = prerenderDecision.reason === "flag" ? "--prerender-all" : "vinext prerender config";
-		const replacement = options.warmCdnCache ? "Routes will be rendered and warmed through the staged Worker instead." : "Use --warm-cache to render and warm routes through the deployed Worker instead.";
+		const replacement = isPreview ? "Preview deployments render these routes on request." : options.warmCdnCache ? "Routes will be rendered and warmed through the staged Worker instead." : "Use --warm-cache to render and warm routes through the deployed Worker instead.";
 		console.warn(`\n  Warning: ${trigger} is ignored by Cloudflare deploy. ${replacement}`);
 	}
-	if (!options.skipBuild) await runBuild(info, deployEnv, viteMode);
+	if (!options.skipBuild) await withBuildContext(() => runBuild(info, cloudflareEnv, viteMode));
 	else console.log("\n  Skipping build (--skip-build)");
 	const prerenderOutputDirs = resolvePrerenderOutputDirs(info.root, deploymentTool, viteConfigMetadata.routeRootConfig);
 	const canWarmTpr = options.experimentalTPR && !shouldPrerenderLocally && hasBuildIdentityHeader;
@@ -1355,15 +1417,21 @@ async function deploy(options) {
 	}
 	if (url === void 0) {
 		if (deploymentTool === "cf" && options.warmCdnPromote === false) url = runCfVersionUpload(root, wranglerOptions).previewUrl ?? "(Preview URL not detected in cf output)";
-		else if (deploymentTool === "cf") url = await runCfDeploy(root, wranglerOptions);
+		else if (deploymentTool === "cf") url = await runCfDeploy(root, {
+			...wranglerOptions,
+			target: options.target
+		});
 		else url = await runWranglerDeploy(root, {
 			...wranglerOptions,
 			promote: options.warmCdnPromote
 		});
 	}
+	printDeployUrl(isPreview ? "Preview URL" : options.warmCdnPromote === false ? "Version URL" : "Deployed to", url);
+}
+function printDeployUrl(label, url) {
 	console.log("\n  ─────────────────────────────────────────");
-	console.log(`  ${options.warmCdnPromote === false ? "Version URL" : "Deployed to"}: ${url}`);
+	console.log(`  ${label}: ${url}`);
 	console.log("  ─────────────────────────────────────────\n");
 }
 //#endregion
-export { DEFAULT_CDN_WARM_PROMOTION_DELAY_MS, buildCfDeployArgs, buildNodeCliInvocation, buildVersionOverrideHeaders, buildWranglerDeployArgs, buildWranglerInvocation, deploy, deployWithCdnWarmup, getZeroPercentStagingTraffic, hasCdnWarmRequests, isCfCliInstalled, parseDeployArgs, projectRequiresRouteCacheabilityProbeManifest, resolveCdnWarmupTargetUrl, resolveCfBin, resolveDeploymentControlPlaneOptions, resolveDeploymentTool, resolvePrerenderOutputDirs, resolveViteBuildMode, resolveWorkerNameForVersionOverride, resolveWranglerBin, runCfDeploy, runWranglerDeploy, selectTPRWarmPlan, validateWranglerEnvName, withCloudflareEnv };
+export { DEFAULT_CDN_WARM_PROMOTION_DELAY_MS, buildCfDeployArgs, buildNodeCliInvocation, buildVersionOverrideHeaders, buildWranglerDeployArgs, buildWranglerInvocation, deploy, deployWithCdnWarmup, getZeroPercentStagingTraffic, hasCdnWarmRequests, isCfCliInstalled, parseDeployArgs, projectRequiresRouteCacheabilityProbeManifest, resolveCdnWarmupTargetUrl, resolveCfBin, resolveDeploymentControlPlaneOptions, resolveDeploymentTool, resolvePrerenderOutputDirs, resolveViteBuildMode, resolveWorkerNameForVersionOverride, resolveWranglerBin, runCfDeploy, runWranglerDeploy, selectTPRWarmPlan, validateWranglerEnvName, withCloudflareEnv, withCloudflarePreviewBuild };

package/dist/previews-deploy.d.ts

@@ -0,0 +1,9 @@
+//#region src/previews-deploy.d.ts
+/** CLI options for `vinext-cloudflare previews deploy`. */
+export declare function parsePreviewsDeployArgs(args: string[]): {
+  help: boolean;
+  name: string | undefined;
+  mode: string | undefined;
+  skipBuild: boolean;
+};
+//#endregion

package/dist/previews-deploy.js

@@ -0,0 +1,43 @@
+import { parseArgs } from "node:util";
+//#region src/previews-deploy.ts
+function validatePreviewName(name) {
+	const trimmed = name.trim();
+	if (!trimmed) throw new Error("Preview name must not be empty.");
+	if (trimmed.includes("\0")) throw new Error("Preview names cannot contain null bytes.");
+	if (trimmed.startsWith("-")) throw new Error("Preview name must not start with '-'.");
+	return trimmed;
+}
+function validateMode(mode) {
+	const trimmed = mode.trim();
+	if (!trimmed) throw new Error("--mode requires a non-empty value.");
+	return trimmed;
+}
+/** CLI options for `vinext-cloudflare previews deploy`. */
+function parsePreviewsDeployArgs(args) {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		strict: true,
+		options: {
+			help: {
+				type: "boolean",
+				short: "h",
+				default: false
+			},
+			mode: { type: "string" },
+			"skip-build": {
+				type: "boolean",
+				default: false
+			}
+		}
+	});
+	if (positionals.length > 1) throw new Error("Expected at most one Preview name: previews deploy [preview-name].");
+	return {
+		help: values.help,
+		name: positionals[0] === void 0 ? void 0 : validatePreviewName(positionals[0]),
+		mode: values.mode === void 0 ? void 0 : validateMode(values.mode),
+		skipBuild: values["skip-build"]
+	};
+}
+//#endregion
+export { parsePreviewsDeployArgs };

package/dist/version-headers.js

@@ -1,2 +1 @@
-import { VINEXT_EXPECTED_WORKER_VERSION_HEADER } from "vinext/internal/server/headers";
-export { VINEXT_EXPECTED_WORKER_VERSION_HEADER };
+export { VINEXT_EXPECTED_WORKER_VERSION_HEADER } from "vinext/internal/server/headers";

package/dist/wrangler-config.d.ts

@@ -16,4 +16,5 @@ type WranglerEnvironmentConfig = {
  * Parse the Wrangler fields used by TPR and staged CDN warming.
  */
 export declare function parseWranglerConfig(root: string, configPath?: string): WranglerConfig | null;
-//#endregion
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinext/cloudflare",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Cloudflare cache and image adapters for vinext.",
   "homepage": "https://vinext.dev/",
   "license": "MIT",
@@ -48,21 +48,20 @@
     }
   },
   "dependencies": {
-    "@cloudflare/workers-response-store": "1.1.1"
+    "@cloudflare/workers-response-store": "1.1.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",
     "cf": "1.0.0-beta.1",
     "miniflare": "5.20260730.0-alpha",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vite-plus": "1.1.0",
-    "vitest": "5.0.3",
-    "vinext": "1.2.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
+    "vite-plus": "1.3.0",
+    "vinext": "1.3.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "*",
     "cf": "*",
-    "vinext": "^1.2.0"
+    "vinext": "^1.3.1"
   },
   "peerDependenciesMeta": {
     "@cloudflare/vite-plugin": {
@@ -78,6 +77,6 @@
   "scripts": {
     "build": "vp pack",
     "dev": "vp pack --watch",
-    "test": "vp run vinext#build && vp run @cloudflare/workers-response-store#build && vp run @vinext/cloudflare#build && VINEXT_RESPONSE_STORE_MODE=self-contained VINEXT_RESPONSE_STORE_LOCATION_HINT=weur pnpm --filter response-store-demo run build && VINEXT_RESPONSE_STORE_LOCATION_HINT=wnam pnpm --filter response-store-demo run build && vitest run"
+    "test": "vp run vinext#build && vp run @cloudflare/workers-response-store#build && vp run @vinext/cloudflare#build && VINEXT_RESPONSE_STORE_MODE=self-contained VINEXT_RESPONSE_STORE_LOCATION_HINT=weur pnpm --filter response-store-demo run build && VINEXT_RESPONSE_STORE_LOCATION_HINT=wnam pnpm --filter response-store-demo run build && vp test run"
   }
 }