cloudflare-next-intl 0.9.46 → 0.9.47

package/README.md

@@ -266,6 +266,7 @@ export default defineConfig({
 4. **User-Agent Stub (`userAgentStub`)**: Prevents Next.js `user-agent` from importing `node:fs` during workerd runtime execution (which otherwise causes runtime 404 / 500 crashes in Workers proxy/middleware).
 5. **Cloudflare Workers Client Stub (`cfWorkersClientStub`)**: Stubs `cloudflare:workers` in client builds so shared modules can be referenced without client bundling errors.
 6. **Build ID Asset Emission (`buildIdAsset`)**: Emits `BUILD_ID` static asset in the client build directory from `process.env.__VINEXT_SHARED_BUILD_ID` or `process.env.__VINEXT_BUILD_ID`.
+7. **Vinext Route Wiring & Optimistic Prefetch Fix (`vinextRouteWiringFix`)**: Patches Vinext runtime route wiring, route matching, optimistic route template resolution, and prefetch learning so pending prefetches with already cached templates don't block navigation, and leading `:locale` segments route correctly.
 
 ##### Plugin Options
 All features are enabled by default, and can be individually configured or toggled off:
@@ -297,13 +298,14 @@ export default defineConfig({
             localeFiles: true,                    // Enable @locale-file & glob bundling (default: true)
             userAgentStub: true,                  // Enable regex-based user-agent stub (default: true)
             cfWorkersClientStub: true,            // Enable client cloudflare:workers stub (default: true)
+            vinextRouteWiringFix: true,           // Enable vinext route wiring, matching, and prefetch fixes (default: true, or options object)
         }),
     ],
 });
 ```
 
 Individual standalone plugins are also exported if you only need a specific feature:
-`imageOptimizerPlugin` (or `imageOptimizer`), `buildIdAsset`, `localeFilePlugin`, `userAgentStubPlugin`, `cfWorkersClientStubPlugin`.
+`imageOptimizerPlugin` (or `imageOptimizer`), `buildIdAsset`, `localeFilePlugin`, `userAgentStubPlugin`, `cfWorkersClientStubPlugin`, `vinextRouteWiringFixPlugin`.
 
 ##### Per-Image Optimizer Settings
 

package/dist/src/vite/vinext_route_wiring_fix.js

@@ -163,13 +163,31 @@ export function isPrefetchLearningFile(id) {
     return cleanId.endsWith("/app-browser-entry.js") || cleanId.endsWith("/app-browser-entry.ts");
 }
 export function isPrefetchLearningAlreadyFixed(code) {
-    const hasFixedFunction = code.includes("isPendingNavigationTarget");
-    const hasFixedCallSite = code.includes("targetRscUrl: rscUrl,");
+    const hasFixedFunction = code.includes("stripRsc(parsePrefetchCacheKey(cacheKey).rscUrl)") && code.includes("hasOptimisticTemplate");
+    const hasFixedCallSite = code.includes("targetHref: currentHref,") && code.includes("targetRscUrl: rscUrl,") && !LEARN_TEMPLATES_CALL_RE.test(code);
     return hasFixedFunction && hasFixedCallSite;
 }
 const LEARN_TEMPLATES_FN_RE = /async\s+function\s+learnOptimisticRouteTemplatesFromPrefetchCache\s*\(\s*options\s*\)\s*\{[\s\S]*?await\s+Promise\.allSettled\(\s*learning\s*\);\s*\}/;
 const FIXED_LEARN_TEMPLATES_FN = `async function learnOptimisticRouteTemplatesFromPrefetchCache(options) {
 	if (options.routeManifest === null) return;
+	const hasOptimisticTemplate = options.targetHref !== void 0 && resolveOptimisticNavigationPayload({
+		basePath: __basePath,
+		href: options.targetHref,
+		interceptionContext: options.interceptionContext,
+		mountedSlotsHeader: options.mountedSlotsHeader,
+		routeManifest: options.routeManifest,
+		templates: optimisticRouteTemplates
+	}) !== null;
+	const stripRsc = (u) => {
+		if (!u) return "";
+		const q = u.indexOf("?");
+		if (q === -1) return u;
+		const sp = new URLSearchParams(u.slice(q + 1));
+		sp.delete("_rsc");
+		sp.delete("%5Frsc");
+		const s = sp.toString();
+		return s ? \`\${u.slice(0, q)}?\${s}\` : u.slice(0, q);
+	};
 	const learning = [...optimisticRouteTemplateLearning.values()];
 	for (const [cacheKey, entry] of getPrefetchCache()) {
 		const sourceKey = getOptimisticPrefetchSourceKey({
@@ -180,7 +198,7 @@ const FIXED_LEARN_TEMPLATES_FN = `async function learnOptimisticRouteTemplatesFr
 		if (optimisticRouteTemplateSources.has(sourceKey)) continue;
 		if (optimisticRouteTemplateLearning.has(sourceKey)) continue;
 		if (entry.prefetchKind === "route-tree") continue;
-		const isPendingNavigationTarget = !isSettledPrefetchCacheEntry(entry) && entry.pending !== void 0 && options.targetRscUrl !== void 0 && parsePrefetchCacheKey(cacheKey).rscUrl === options.targetRscUrl;
+		const isPendingNavigationTarget = !hasOptimisticTemplate && !isSettledPrefetchCacheEntry(entry) && entry.pending !== void 0 && options.targetRscUrl !== void 0 && stripRsc(parsePrefetchCacheKey(cacheKey).rscUrl) === stripRsc(options.targetRscUrl);
 		if (!isSettledPrefetchCacheEntry(entry) && !isPendingNavigationTarget) continue;
 		const promise = (async () => {
 			let settledEntry = entry;
@@ -210,17 +228,23 @@ const FIXED_LEARN_TEMPLATES_FN = `async function learnOptimisticRouteTemplatesFr
 	if (learning.length === 0) return;
 	await Promise.allSettled(learning);
 }`;
-const LEARN_TEMPLATES_CALL_RE = /(await\s+learnOptimisticRouteTemplatesFromPrefetchCache\(\s*\{\s*)interceptionContext:\s*requestInterceptionContext,/;
-const FIXED_LEARN_TEMPLATES_CALL = "$1interceptionContext: requestInterceptionContext,\n\t\t\t\t\t\t\ttargetRscUrl: rscUrl,";
+const LEARN_TEMPLATES_CALL_RE = /await\s+learnOptimisticRouteTemplatesFromPrefetchCache\(\s*\{\s*interceptionContext:\s*requestInterceptionContext,\s*(targetRscUrl:\s*rscUrl,\s*)?mountedSlotsHeader,[\s\S]*?routeManifest\s*\n\s*\}\);/;
+const FIXED_LEARN_TEMPLATES_CALL = `await learnOptimisticRouteTemplatesFromPrefetchCache({
+							interceptionContext: requestInterceptionContext,
+							targetHref: currentHref,
+							targetRscUrl: rscUrl,
+							mountedSlotsHeader,
+							routeManifest
+						});`;
 export function patchPrefetchLearning(code) {
     if (isPrefetchLearningAlreadyFixed(code)) {
         return code;
     }
     let result = code;
-    if (!result.includes("isPendingNavigationTarget") && LEARN_TEMPLATES_FN_RE.test(result)) {
+    if (!result.includes("hasOptimisticTemplate") && LEARN_TEMPLATES_FN_RE.test(result)) {
         result = result.replace(LEARN_TEMPLATES_FN_RE, FIXED_LEARN_TEMPLATES_FN);
     }
-    if (!result.includes("targetRscUrl: rscUrl,") && LEARN_TEMPLATES_CALL_RE.test(result)) {
+    if (LEARN_TEMPLATES_CALL_RE.test(result)) {
         result = result.replace(LEARN_TEMPLATES_CALL_RE, FIXED_LEARN_TEMPLATES_CALL);
     }
     return result;

package/llms.txt

@@ -27,7 +27,7 @@ other subpath can be used.
 - `./db` — `withPublicDb(fn)` / `withUserDb(fn, uid?)` server-side Postgres/Drizzle context helpers (require `db` set on your `RoutingConfig`; direct Postgres or Supabase Data API with automatic PostgREST REST translation and `cfni_exec` fallback, see below).
 - `./dbEslint` — flat-config ESLint fragment banning direct `@supabase/supabase-js`, `pg`, `postgres`, and deep `dist/` imports in application code.
 - `./dbHelpers` — generic Drizzle SQL helper functions (`excluded`, `onConflictSet`, `ago`, `currentDate`, `windowCount`, `unnestLateral`, `ascNullsLast`, `alwaysTrue`, `lateral`, `aliasColumn`, `minOf`, `maxOf`, `roundReal`, `multiply`, `scalarFromCte`) for use with `./db`.
-- `./vite` — `cloudflareNextIntl(options?)` / `cloudflareNextIntlPlugin`, `imageOptimizerPlugin(options?)` / `imageOptimizer`, `buildIdAsset(fileName?)`, `localeFilePlugin(options?)`, `userAgentStubPlugin()`, `cfWorkersClientStubPlugin()`: All-in-one Vite plugin required for Vinext/Cloudflare Workers environments (bundles `@locale-file/*` via eager glob, resolves `@intl-config`, stubs Node.js `user-agent` to prevent runtime `node:fs` errors, stubs `cloudflare:workers` for client builds, emits client `BUILD_ID`, and runs build-time/dev Image Optimizer with Next.js blur placeholder shimming).
+- `./vite` — `cloudflareNextIntl(options?)` / `cloudflareNextIntlPlugin`, `imageOptimizerPlugin(options?)` / `imageOptimizer`, `buildIdAsset(fileName?)`, `localeFilePlugin(options?)`, `userAgentStubPlugin()`, `cfWorkersClientStubPlugin()`, `vinextRouteWiringFixPlugin(options?)`: All-in-one Vite plugin required for Vinext/Cloudflare Workers environments (bundles `@locale-file/*` via eager glob, resolves `@intl-config`, stubs Node.js `user-agent` to prevent runtime `node:fs` errors, stubs `cloudflare:workers` for client builds, emits client `BUILD_ID`, runs build-time/dev Image Optimizer with Next.js blur placeholder shimming, and fixes vinext route wiring, matching, and non-blocking optimistic prefetch learning).
 - `./image-optimizer` / `./imageOptimizer` — image optimization suite: `imageOptimizerPlugin`, `imageOptimizer`, `resolveOptions`, `resolveImageConfig`, `resolveBlurOptions`, `processImage`, `makeBlurDataURL`, `getImageBlurSvg`, `renderManifest`, `writeManifest`, `isFresh`, `loadCache`, `saveCache`, `collectImages`, `run`.
 - `./errorHandling` — error reporting & stale deploy recovery barrel: `reportError`, `withErrorHandling`, `installConsoleErrorOverride`, `installGlobalErrorOverride`, `stringifyUnknown`, `formatErrorMessage`, `defaultIgnoredConsoleErrors`, `createServerErrorAction`, `isStaleDeployError`, `defaultStaleDeployPatterns`, `setStaleDeployPatterns`, `getStaleDeployPatterns`, `clearClientCache`, `useStaleDeployRecovery`, `shouldRecoverFromStaleDeploy`, `isRecentBuild`.
 - `./isStaleDeployError` — `isStaleDeployError(error, patterns?)`, `setStaleDeployPatterns(patterns)`, `getStaleDeployPatterns()`: detector returning `true` for version skew / chunk load / dynamic import / server action 404 / hydration errors (ChunkLoadError, UnrecognizedActionError, server action not found, failed to fetch, dynamically imported module failure, loading CSS chunk, connection closed, RSC payload failure, minified error #412, or missing stream error `undefined`) with fast pre-lowercased pattern cache and intl-config integration (`errorHandling.staleDeployPatterns`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.9.46",
+  "version": "0.9.47",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",