vinext 0.0.55 → 0.1.0

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

@@ -0,0 +1,97 @@
+import { getRequestExecutionContext } from "../../../shims/request-context.js";
+//#region ../cloudflare/src/cache/cdn-adapter.runtime.ts
+function getWorkersCache() {
+	const cache = getRequestExecutionContext()?.cache;
+	if (cache && typeof cache.purge === "function") return cache;
+	return null;
+}
+/** Non-cacheable responses: nobody (edge or browser) stores them. */
+const NO_STORE = "no-store";
+/**
+* Browser-facing policy for cacheable responses. `public` allows shared caches
+* to participate, but `max-age=0, must-revalidate` forces every reuse to
+* revalidate (against the edge) rather than serving a stored copy — so the user
+* always sees edge-fresh content while still permitting conditional 304s.
+*/
+const BROWSER_REVALIDATE = "public, max-age=0, must-revalidate";
+/**
+* A concrete stale window (1 year) substituted for a value-less
+* `stale-while-revalidate`. The framework emits a bare `stale-while-revalidate`
+* (no `=seconds`) to mean an unbounded stale window — a Vercel CDN extension.
+* Cloudflare follows RFC 5861, which requires `stale-while-revalidate=<seconds>`,
+* and treats the value-less form as a zero-width window (no stale serving →
+* hard expiry at `max-age`, so the next request is a MISS instead of UPDATING).
+* Stamping a large finite value preserves the "serve stale ~indefinitely while
+* revalidating" intent in a form the edge honors.
+*/
+const UNBOUNDED_SWR_SECONDS = 31536e3;
+/**
+* Convert the framework's shared-cache policy into a CDN-scoped one:
+* `s-maxage=…` → `max-age=…` (the edge honors `max-age` inside
+* `CDN-Cache-Control`), give a value-less `stale-while-revalidate` an explicit
+* seconds value (Cloudflare ignores the bare directive), and ensure a leading
+* `public`.
+*/
+function toEdgeCacheControl(cacheControl) {
+	const withMaxAge = cacheControl.replace(/\bs-maxage=/g, "max-age=").replace(/\bstale-while-revalidate\b(?!=)/g, `stale-while-revalidate=${UNBOUNDED_SWR_SECONDS}`);
+	return /\bpublic\b/.test(withMaxAge) ? withMaxAge : `public, ${withMaxAge}`;
+}
+/**
+* Cloudflare's `Cache-Tag` header budget is 16 KB total with each tag capped at
+* 1024 bytes. Keep a conservative ceiling so a page with a large tag set never
+* produces an oversized (silently-dropped) header.
+*/
+const MAX_CACHE_TAG_BYTES = 8 * 1024;
+const MAX_SINGLE_TAG_BYTES = 1024;
+/**
+* Build a `Cache-Tag` header value from canonicalised tags. Tags containing a
+* comma (the header separator) or exceeding the per-tag size are skipped, and
+* the whole value is bounded to stay within Cloudflare's limit.
+*/
+function formatCacheTag(tags) {
+	const parts = [];
+	let total = 0;
+	for (const tag of tags) {
+		if (!tag || tag.includes(",") || tag.length > MAX_SINGLE_TAG_BYTES) continue;
+		const next = total + tag.length + (parts.length > 0 ? 1 : 0);
+		if (next > MAX_CACHE_TAG_BYTES) break;
+		parts.push(tag);
+		total = next;
+	}
+	return parts.length > 0 ? parts.join(",") : null;
+}
+var CloudflareCdnCacheAdapter = class {
+	ownsBackgroundRevalidation = false;
+	/**
+	* The origin keeps no page store — return null so the request renders fresh.
+	* The edge serves cached HIT/STALE responses without reaching the origin.
+	*/
+	async get() {
+		return null;
+	}
+	/** No-op: the platform caches the response via its headers, not an origin store. */
+	async set(_key, _data, _ctx) {}
+	buildResponseHeaders(input) {
+		if (!input.cacheControl) return { "Cache-Control": NO_STORE };
+		if (/\b(?:no-store|no-cache|private)\b/.test(input.cacheControl)) return { "Cache-Control": input.cacheControl };
+		const headers = {
+			"Cache-Control": BROWSER_REVALIDATE,
+			"CDN-Cache-Control": toEdgeCacheControl(input.cacheControl)
+		};
+		if (input.tags && input.tags.length > 0) {
+			const cacheTag = formatCacheTag(input.tags);
+			if (cacheTag) headers["Cache-Tag"] = cacheTag;
+		}
+		return headers;
+	}
+	/** Purge edge-cached responses by tag via the request context's `cache.purge`. */
+	async revalidateTag(tags, _durations) {
+		const cache = getWorkersCache();
+		if (!cache) return;
+		const tagList = (Array.isArray(tags) ? tags : [tags]).filter((t) => typeof t === "string" && t.length > 0);
+		if (tagList.length === 0) return;
+		await cache.purge({ tags: tagList });
+	}
+};
+//#endregion
+export { CloudflareCdnCacheAdapter };

package/dist/cloudflare/{kv-cache-handler.d.ts → src/cache/kv-data-adapter.runtime.d.ts}

@@ -1,7 +1,7 @@
-import { ExecutionContextLike } from "../shims/request-context.js";
-import { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "../shims/cache.js";
+import { ExecutionContextLike } from "../../../shims/request-context.js";
+import { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "../../../shims/cache.js";
 
-//#region src/cloudflare/kv-cache-handler.d.ts
+//#region ../cloudflare/src/cache/kv-data-adapter.runtime.d.ts
 type KVNamespace = {
   get(key: string, options?: {
     type?: string;
@@ -28,7 +28,27 @@ type KVNamespace = {
   }>;
 };
 /** Key prefix for cache entries. */
-declare const ENTRY_PREFIX = "cache:";
+/**
+ * Cloudflare KV data cache handler.
+ *
+ * @deprecated Consumers should not instantiate or register this handler by
+ * hand. Configure it declaratively via the `cache.data` option on the
+ * `vinext()` plugin, using the {@link kvDataAdapter} builder:
+ *
+ * ```ts
+ * import { vinext } from "vinext";
+ * import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
+ *
+ * export default defineConfig({
+ *   plugins: [vinext({ cache: { data: kvDataAdapter({ binding: "VINEXT_KV_CACHE" }) } })],
+ * });
+ * ```
+ *
+ * `kvDataAdapter()` is safe to call from `vite.config.ts` — it never touches
+ * the Workers runtime — and the plugin defers instantiation of this handler to
+ * the first request. This class stays exported for the runtime factory and for
+ * backwards compatibility, but is not the recommended consumer API.
+ */
 declare class KVCacheHandler implements CacheHandler {
   private kv;
   private prefix;
@@ -103,5 +123,4 @@ declare class KVCacheHandler implements CacheHandler {
   private _put;
 }
 //#endregion
-export { ENTRY_PREFIX, KVCacheHandler };
-//# sourceMappingURL=kv-cache-handler.d.ts.map
+export { KVCacheHandler };

package/dist/cloudflare/{kv-cache-handler.js → src/cache/kv-data-adapter.runtime.js}

@@ -1,36 +1,25 @@
-import { getRequestExecutionContext } from "../shims/request-context.js";
-import { isUnknownRecord } from "../utils/record.js";
-import { readCacheControlNumberField } from "../utils/cache-control-metadata.js";
+import { getRequestExecutionContext } from "../../../shims/request-context.js";
+import { isUnknownRecord, readCacheControlNumberField } from "../utils/cache-control-metadata.js";
 import { Buffer } from "node:buffer";
-//#region src/cloudflare/kv-cache-handler.ts
+//#region ../cloudflare/src/cache/kv-data-adapter.runtime.ts
 /**
-* Cloudflare KV-backed CacheHandler for vinext.
+* Cloudflare KV data cache — implementation + runtime factory.
 *
-* Provides persistent ISR caching on Cloudflare Workers using KV as the
-* storage backend. Supports time-based expiry (stale-while-revalidate)
-* and tag-based invalidation.
+* `KVCacheHandler` provides persistent ISR caching on Cloudflare Workers using
+* KV as the storage backend (time-based expiry / stale-while-revalidate and
+* tag-based invalidation). The default export is the adapter factory the
+* generated `virtual:vinext-cache-adapters` registration imports: it reads the
+* KV namespace from `env[binding]` at request time and constructs the handler.
 *
-* Usage in worker/index.ts:
-*
-*   import { KVCacheHandler } from "vinext/cloudflare";
-*   import { setCacheHandler } from "vinext/shims/cache";
-*
-*   export default {
-*     async fetch(request: Request, env: Env, ctx: ExecutionContext) {
-*       setCacheHandler(new KVCacheHandler(env.VINEXT_CACHE));
-*       // ctx is propagated automatically via runWithExecutionContext in
-*       // the vinext handler — no need to pass it to KVCacheHandler.
-*       // ... rest of worker handler
-*     }
-*   };
+* Configure it from vite.config via the {@link kvDataAdapter} builder in
+* `./kv-data-adapter.ts` (which `require.resolve`s this file). The legacy
+* imperative path (constructing `KVCacheHandler` and calling
+* `setDataCacheHandler` from a worker entry) is deprecated — prefer the
+* `cache.data` plugin option.
 *
 * Wrangler config (wrangler.jsonc):
 *
-*   {
-*     "kv_namespaces": [
-*       { "binding": "VINEXT_CACHE", "id": "<your-kv-namespace-id>" }
-*     ]
-*   }
+*   { "kv_namespaces": [{ "binding": "VINEXT_KV_CACHE", "id": "<your-kv-namespace-id>" }] }
 */
 /** Key prefix for tag invalidation timestamps. */
 const TAG_PREFIX = "__tag:";
@@ -78,6 +67,27 @@ function isPathChildOf(path, prefix) {
 	if (path === prefix) return true;
 	return path.startsWith(prefix + "/");
 }
+/**
+* Cloudflare KV data cache handler.
+*
+* @deprecated Consumers should not instantiate or register this handler by
+* hand. Configure it declaratively via the `cache.data` option on the
+* `vinext()` plugin, using the {@link kvDataAdapter} builder:
+*
+* ```ts
+* import { vinext } from "vinext";
+* import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
+*
+* export default defineConfig({
+*   plugins: [vinext({ cache: { data: kvDataAdapter({ binding: "VINEXT_KV_CACHE" }) } })],
+* });
+* ```
+*
+* `kvDataAdapter()` is safe to call from `vite.config.ts` — it never touches
+* the Workers runtime — and the plugin defers instantiation of this handler to
+* the first request. This class stays exported for the runtime factory and for
+* backwards compatibility, but is not the recommended consumer API.
+*/
 var KVCacheHandler = class {
 	kv;
 	prefix;
@@ -423,5 +433,3 @@ function safeBase64ToArrayBuffer(base64) {
 }
 //#endregion
 export { ENTRY_PREFIX, KVCacheHandler };
-
-//# sourceMappingURL=kv-cache-handler.js.map

package/dist/cloudflare/src/utils/cache-control-metadata.js

@@ -0,0 +1,20 @@
+//#region ../cloudflare/src/utils/cache-control-metadata.ts
+/**
+* Small internal helpers for reading cache-control metadata off the loosely
+* typed `ctx` object the cache layer passes around. Kept local to this package
+* so the Cloudflare adapters stay self-contained (these mirror the equivalent
+* helpers in the vinext core).
+*/
+function isUnknownRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readRecordField(ctx, field) {
+	const value = ctx?.[field];
+	return isUnknownRecord(value) ? value : void 0;
+}
+function readCacheControlNumberField(ctx, field) {
+	const value = readRecordField(ctx, "cacheControl")?.[field] ?? ctx?.[field];
+	return typeof value === "number" ? value : void 0;
+}
+//#endregion
+export { isUnknownRecord, readCacheControlNumberField };

package/dist/cloudflare/tpr.d.ts

@@ -45,7 +45,7 @@ type WranglerConfig = {
 };
 /**
  * Parse wrangler config (JSONC or TOML) to extract the fields TPR needs:
- * account_id, VINEXT_CACHE KV namespace ID, and custom domain.
+ * account_id, VINEXT_KV_CACHE KV namespace ID, and custom domain.
  */
 declare function parseWranglerConfig(root: string): WranglerConfig | null;
 /**
@@ -79,5 +79,4 @@ declare function buildTprKVPairs(entries: Map<string, PrerenderResult>, buildId:
  */
 declare function runTPR(options: TPROptions): Promise<TPRResult>;
 //#endregion
-export { TPROptions, TPRResult, buildTprKVPairs, domainCandidates, parseWranglerConfig, runTPR };
-//# sourceMappingURL=tpr.d.ts.map
+export { TPROptions, TPRResult, buildTprKVPairs, domainCandidates, parseWranglerConfig, runTPR };

package/dist/cloudflare/tpr.js

@@ -1,6 +1,7 @@
 import { VINEXT_REVALIDATE_HEADER } from "../server/headers.js";
 import { isrCacheKey } from "../server/isr-cache.js";
-import { ENTRY_PREFIX } from "./kv-cache-handler.js";
+import { buildAppPageCacheTags } from "../server/app-page-cache.js";
+import { ENTRY_PREFIX } from "./src/cache/kv-data-adapter.runtime.js";
 import fs from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
@@ -28,7 +29,7 @@ import { spawn } from "node:child_process";
 */
 /**
 * Parse wrangler config (JSONC or TOML) to extract the fields TPR needs:
-* account_id, VINEXT_CACHE KV namespace ID, and custom domain.
+* account_id, VINEXT_KV_CACHE KV namespace ID, and custom domain.
 */
 function parseWranglerConfig(root) {
 	for (const filename of ["wrangler.jsonc", "wrangler.json"]) {
@@ -111,7 +112,7 @@ function extractFromJSON(config) {
 	const result = {};
 	if (typeof config.account_id === "string") result.accountId = config.account_id;
 	if (Array.isArray(config.kv_namespaces)) {
-		const vinextKV = config.kv_namespaces.find((ns) => ns && typeof ns === "object" && ns.binding === "VINEXT_CACHE");
+		const vinextKV = config.kv_namespaces.find((ns) => ns && typeof ns === "object" && (ns.binding === "VINEXT_KV_CACHE" || ns.binding === "VINEXT_CACHE"));
 		if (vinextKV && typeof vinextKV.id === "string" && vinextKV.id !== "<your-kv-namespace-id>") result.kvNamespaceId = vinextKV.id;
 	}
 	const domain = extractDomainFromRoutes(config.routes) ?? extractDomainFromCustomDomains(config);
@@ -156,7 +157,7 @@ function extractFromTOML(content) {
 		const block = kvBlocks[i].split(/\[\[/)[0];
 		const bindingMatch = block.match(/binding\s*=\s*"([^"]+)"/);
 		const idMatch = block.match(/\bid\s*=\s*"([^"]+)"/);
-		if (bindingMatch?.[1] === "VINEXT_CACHE" && idMatch?.[1] && idMatch[1] !== "<your-kv-namespace-id>") result.kvNamespaceId = idMatch[1];
+		if ((bindingMatch?.[1] === "VINEXT_KV_CACHE" || bindingMatch?.[1] === "VINEXT_CACHE") && idMatch?.[1] && idMatch[1] !== "<your-kv-namespace-id>") result.kvNamespaceId = idMatch[1];
 	}
 	const routeMatch = content.match(/^route\s*=\s*"([^"]+)"/m);
 	if (routeMatch) {
@@ -427,6 +428,7 @@ function buildTprKVPairs(entries, buildId, defaultRevalidateSeconds) {
 		const revalidateSeconds = revalidateHeader && !isNaN(Number(revalidateHeader)) ? Number(revalidateHeader) : defaultRevalidateSeconds;
 		const revalidateAt = revalidateSeconds > 0 ? now + revalidateSeconds * 1e3 : null;
 		const kvTtl = revalidateSeconds > 0 ? MAX_KV_TTL_SECONDS : 24 * 3600;
+		const tags = buildAppPageCacheTags(routePath, []);
 		const entry = {
 			value: {
 				kind: "APP_PAGE",
@@ -434,7 +436,7 @@ function buildTprKVPairs(entries, buildId, defaultRevalidateSeconds) {
 				headers: result.headers,
 				status: result.status
 			},
-			tags: [],
+			tags,
 			lastModified: now,
 			revalidateAt
 		};
@@ -494,7 +496,7 @@ async function runTPR(options) {
 	const wranglerConfig = parseWranglerConfig(root);
 	if (!wranglerConfig) return skip("could not parse wrangler config");
 	if (!wranglerConfig.customDomain) return skip("no custom domain — zone analytics unavailable");
-	if (!wranglerConfig.kvNamespaceId) return skip("no VINEXT_CACHE KV namespace configured");
+	if (!wranglerConfig.kvNamespaceId) return skip("no VINEXT_KV_CACHE KV namespace configured");
 	const accountId = wranglerConfig.accountId ?? await resolveAccountId(apiToken);
 	if (!accountId) return skip("could not resolve Cloudflare account ID");
 	console.log(`  TPR: Analyzing traffic for ${wranglerConfig.customDomain} (last ${windowHours}h)`);
@@ -554,5 +556,3 @@ async function runTPR(options) {
 }
 //#endregion
 export { buildTprKVPairs, domainCandidates, parseWranglerConfig, runTPR };
-
-//# sourceMappingURL=tpr.js.map

package/dist/config/config-matchers.d.ts

@@ -218,5 +218,4 @@ declare function applyLocaleToRoutes<T extends NextRedirect | NextRewrite>(route
   trailingSlash?: boolean;
 }): T[];
 //#endregion
-export { BasePathMatchState, RequestContext, applyLocaleToRoutes, applyMiddlewareRequestHeaders, checkHasConditions, escapeHeaderSource, isExternalUrl, isSafeRegex, matchConfigPattern, matchHeaders, matchRedirect, matchRewrite, normalizeHost, parseCookies, proxyExternalRequest, requestContextFromRequest, safeRegExp, sanitizeDestination };
-//# sourceMappingURL=config-matchers.d.ts.map
+export { BasePathMatchState, RequestContext, applyLocaleToRoutes, applyMiddlewareRequestHeaders, checkHasConditions, escapeHeaderSource, isExternalUrl, isSafeRegex, matchConfigPattern, matchHeaders, matchRedirect, matchRewrite, normalizeHost, parseCookies, proxyExternalRequest, requestContextFromRequest, safeRegExp, sanitizeDestination };

package/dist/config/config-matchers.js

@@ -926,5 +926,3 @@ function applyLocaleToRoutes(routes, i18n, type, options = {}) {
 }
 //#endregion
 export { applyLocaleToRoutes, applyMiddlewareRequestHeaders, checkHasConditions, escapeHeaderSource, isExternalUrl, isSafeRegex, matchConfigPattern, matchHeaders, matchRedirect, matchRewrite, normalizeHost, parseCookies, proxyExternalRequest, requestContextFromRequest, safeRegExp, sanitizeDestination };
-
-//# sourceMappingURL=config-matchers.js.map

package/dist/config/dotenv.d.ts

@@ -53,5 +53,4 @@ declare function loadDotenv({
   processEnv
 }: LoadDotenvOptions): LoadDotenvResult;
 //#endregion
-export { getDotenvFiles, loadDotenv };
-//# sourceMappingURL=dotenv.d.ts.map
+export { getDotenvFiles, loadDotenv };

package/dist/config/dotenv.js

@@ -86,5 +86,3 @@ function expandEnv(parsed, processEnv) {
 }
 //#endregion
 export { getDotenvFiles, loadDotenv };
-
-//# sourceMappingURL=dotenv.js.map

package/dist/config/next-config.d.ts

@@ -416,6 +416,21 @@ declare function loadNextConfig(root: string, phase?: string): Promise<NextConfi
  * @see https://nextjs.org/docs/app/api-reference/config/next-config-js/assetPrefix
  */
 declare function normalizeAssetPrefix(value: unknown): string;
+/**
+ * Resolve the App Router RSC compatibility identity for a build.
+ *
+ * This token is baked into the client bundle and echoed by the server in the
+ * `X-Vinext-RSC-Compatibility-Id` response header; browser navigation rejects
+ * RSC payloads whose token differs (deploy skew) without exposing the raw
+ * build ID. When the user pins a `deploymentId` we reuse it (already stable
+ * across plugin instances); otherwise we mint a random UUID.
+ *
+ * NOTE: like `resolveBuildId`, this is non-deterministic in the no-deploymentId
+ * case, so a single `vinext build` that instantiates the plugin more than once
+ * (App Router `buildApp()` + the hybrid Pages Router `vite.build()`) must
+ * resolve it once and share it — see `__VINEXT_SHARED_RSC_COMPATIBILITY_ID`.
+ */
+declare function createRscCompatibilityId(nextConfig: Pick<ResolvedNextConfig, "deploymentId">): string;
 /**
  * Resolve a NextConfig into a fully-resolved ResolvedNextConfig.
  * Awaits async functions for redirects/rewrites/headers.
@@ -448,5 +463,4 @@ declare function extractMdxOptions(config: NextConfig, root?: string): Promise<M
  */
 declare function detectNextIntlConfig(root: string, resolved: ResolvedNextConfig): void;
 //#endregion
-export { HasCondition, MdxOptions, NextConfig, NextConfigFactory, NextConfigInput, NextHeader, NextI18nConfig, NextRedirect, NextRewrite, PHASE_PRODUCTION_BUILD, ResolvedNextConfig, detectNextIntlConfig, extractMdxOptions, findNextConfigPath, loadNextConfig, normalizeAssetPrefix, parseBodySizeLimit, reassignsModuleExports, referencesCjsGlobals, resolveNextConfig, resolveNextConfigInput };
-//# sourceMappingURL=next-config.d.ts.map
+export { HasCondition, MdxOptions, NextConfig, NextConfigInput, NextHeader, NextI18nConfig, NextRedirect, NextRewrite, PHASE_PRODUCTION_BUILD, ResolvedNextConfig, createRscCompatibilityId, detectNextIntlConfig, extractMdxOptions, findNextConfigPath, loadNextConfig, normalizeAssetPrefix, parseBodySizeLimit, reassignsModuleExports, referencesCjsGlobals, resolveNextConfig, resolveNextConfigInput };

package/dist/config/next-config.js

@@ -224,12 +224,15 @@ function cjsGlobalsInjectorPlugin(configPath) {
 			const filenameLiteral = JSON.stringify(normalizedTarget);
 			const dirnameLiteral = JSON.stringify(dirname);
 			const requireBaseLiteral = JSON.stringify(path.join(dirname, "package.json"));
+			const hasOwnDirname = /\b(?:const|let|var)\s+__dirname\b/.test(code);
+			const hasOwnFilename = /\b(?:const|let|var)\s+__filename\b/.test(code);
+			const hasOwnRequire = /\b(?:const|let|var)\s+require\b/.test(code);
 			const moduleLines = reassignsModuleExports(code) ? `const __vinextInitialExports = {};
 const module = { exports: __vinextInitialExports };
 const exports = module.exports;
 export const ${VINEXT_CJS_EXPORTS_KEY} = module;\nexport const ${VINEXT_CJS_INITIAL_KEY} = __vinextInitialExports;\n` : "";
 			return {
-				code: `import { createRequire as __vinextCreateRequire } from "node:module";\nconst __filename = ${filenameLiteral};\nconst __dirname = ${dirnameLiteral};\nconst require = __vinextCreateRequire(${requireBaseLiteral});\n` + moduleLines + code,
+				code: (hasOwnRequire ? "" : `import { createRequire as __vinextCreateRequire } from "node:module";\n`) + (hasOwnFilename ? "" : `const __filename = ${filenameLiteral};\n`) + (hasOwnDirname ? "" : `const __dirname = ${dirnameLiteral};\n`) + (hasOwnRequire ? "" : `const require = __vinextCreateRequire(${requireBaseLiteral});\n`) + moduleLines + code,
 				map: null
 			};
 		}
@@ -394,6 +397,24 @@ function resolveDeploymentId(configDeploymentId) {
 	return deploymentId;
 }
 /**
+* Resolve the App Router RSC compatibility identity for a build.
+*
+* This token is baked into the client bundle and echoed by the server in the
+* `X-Vinext-RSC-Compatibility-Id` response header; browser navigation rejects
+* RSC payloads whose token differs (deploy skew) without exposing the raw
+* build ID. When the user pins a `deploymentId` we reuse it (already stable
+* across plugin instances); otherwise we mint a random UUID.
+*
+* NOTE: like `resolveBuildId`, this is non-deterministic in the no-deploymentId
+* case, so a single `vinext build` that instantiates the plugin more than once
+* (App Router `buildApp()` + the hybrid Pages Router `vite.build()`) must
+* resolve it once and share it — see `__VINEXT_SHARED_RSC_COMPATIBILITY_ID`.
+*/
+function createRscCompatibilityId(nextConfig) {
+	if (nextConfig.deploymentId) return nextConfig.deploymentId;
+	return randomUUID();
+}
+/**
 * Converts a cache handler path to a filesystem path.
 * ESM's import.meta.resolve() returns file:// URLs which break when concatenated
 * with path operations like path.join or path.relative.
@@ -881,6 +902,4 @@ function extractPluginsFromOptions(opts) {
 	return null;
 }
 //#endregion
-export { PHASE_PRODUCTION_BUILD, detectNextIntlConfig, extractMdxOptions, findNextConfigPath, loadNextConfig, normalizeAssetPrefix, parseBodySizeLimit, reassignsModuleExports, referencesCjsGlobals, resolveNextConfig, resolveNextConfigInput };
-
-//# sourceMappingURL=next-config.js.map
+export { PHASE_PRODUCTION_BUILD, createRscCompatibilityId, detectNextIntlConfig, extractMdxOptions, findNextConfigPath, loadNextConfig, normalizeAssetPrefix, parseBodySizeLimit, reassignsModuleExports, referencesCjsGlobals, resolveNextConfig, resolveNextConfigInput };

package/dist/config/tsconfig-paths.d.ts

@@ -18,5 +18,4 @@ declare function loadTsconfigResolutionForRoot(projectRoot: string): TsconfigPat
  */
 declare function loadTsconfigPathAliasesForRoot(projectRoot: string): Record<string, string>;
 //#endregion
-export { loadTsconfigPathAliasesForRoot, loadTsconfigResolutionForRoot };
-//# sourceMappingURL=tsconfig-paths.d.ts.map
+export { loadTsconfigPathAliasesForRoot, loadTsconfigResolutionForRoot };

package/dist/config/tsconfig-paths.js

@@ -1,3 +1,4 @@
+import { isUnknownRecord } from "../utils/record.js";
 import { parseStaticObjectLiteral } from "../plugins/fonts.js";
 import { createRequire } from "node:module";
 import fs from "node:fs";
@@ -28,9 +29,6 @@ import path from "node:path";
 *     `runnerImport`'s inline environment (which has its own root).
 */
 const TSCONFIG_FILES = ["tsconfig.json", "jsconfig.json"];
-function isRecord(value) {
-	return !!value && typeof value === "object" && !Array.isArray(value);
-}
 function resolveTsconfigPathCandidate(candidate) {
 	const candidates = candidate.endsWith(".json") ? [candidate] : [
 		candidate,
@@ -103,9 +101,9 @@ function loadResolutionFromTsconfigFile(configPath, seen) {
 			};
 		}
 	}
-	const compilerOptions = isRecord(parsed.compilerOptions) ? parsed.compilerOptions : null;
+	const compilerOptions = isUnknownRecord(parsed.compilerOptions) ? parsed.compilerOptions : null;
 	const baseUrl = (compilerOptions && typeof compilerOptions.baseUrl === "string" ? path.resolve(path.dirname(configPath), compilerOptions.baseUrl) : null) ?? resolution.baseUrl;
-	const pathsConfig = compilerOptions && isRecord(compilerOptions.paths) ? compilerOptions.paths : null;
+	const pathsConfig = compilerOptions && isUnknownRecord(compilerOptions.paths) ? compilerOptions.paths : null;
 	if (!pathsConfig) return {
 		aliases: resolution.aliases,
 		baseUrl
@@ -144,5 +142,3 @@ function loadTsconfigPathAliasesForRoot(projectRoot) {
 }
 //#endregion
 export { loadTsconfigPathAliasesForRoot, loadTsconfigResolutionForRoot };
-
-//# sourceMappingURL=tsconfig-paths.js.map

package/dist/deploy.d.ts

@@ -65,7 +65,7 @@ declare const renameCJSConfigs: typeof renameCJSConfigs$1;
 /** Generate wrangler.jsonc content */
 declare function generateWranglerConfig(info: ProjectInfo): string;
 /** Generate worker/index.ts for App Router */
-declare function generateAppRouterWorkerEntry(hasISR?: boolean): string;
+declare function generateAppRouterWorkerEntry(): string;
 /** Generate worker/index.ts for Pages Router */
 declare function generatePagesRouterWorkerEntry(): string;
 /** Generate vite.config.ts for App Router */
@@ -100,7 +100,53 @@ type GeneratedFile = {
  * virtual:vinext-rsc-entry").
  */
 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;
+/**
+ * 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 getFilesToGenerate(info: ProjectInfo): GeneratedFile[];
+/**
+ * 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;
@@ -122,5 +168,4 @@ declare function buildWranglerDeployArgs(options: Pick<DeployOptions, "preview"
 declare function resolveWranglerBin(root: string, platform?: NodeJS.Platform): string;
 declare function deploy(options: DeployOptions): Promise<void>;
 //#endregion
-export { buildWranglerDeployArgs, deploy, detectProject, ensureESModule, formatMissingCloudflarePluginError, generateAppRouterViteConfig, generateAppRouterWorkerEntry, generatePagesRouterViteConfig, generatePagesRouterWorkerEntry, generateWranglerConfig, getFilesToGenerate, getMissingDeps, hasWranglerConfig, isPackageResolvable, parseDeployArgs, renameCJSConfigs, resolveWranglerBin, viteConfigHasCloudflarePlugin };
-//# sourceMappingURL=deploy.d.ts.map
+export { buildWranglerDeployArgs, deploy, detectProject, ensureESModule, formatMissingCacheAdapterError, formatMissingCloudflarePluginError, generateAppRouterViteConfig, generateAppRouterWorkerEntry, generatePagesRouterViteConfig, generatePagesRouterWorkerEntry, generateWranglerConfig, getFilesToGenerate, getMissingDeps, hasWranglerConfig, isPackageResolvable, parseDeployArgs, renameCJSConfigs, resolveWranglerBin, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, withCloudflareEnv, workerEntryHasCacheHandler };