cloudflare-next-intl 0.8.41 → 0.8.43

package/README.md

@@ -217,6 +217,8 @@ export function customHandler(request: NextRequest) {
 
 `intlMiddleware` automatically forwards `x-cf-country` and `x-cf-timezone` headers from `request.cf` so they are immediately available downstream via `next/headers`.
 
+Header names default to `['x-cf-country', 'cf-ipcountry']` and `['x-cf-timezone', 'cf-timezone']`. You can customize them globally in `setIntlConfig({ generate: { countryHeaderNames: [...], timezoneHeaderNames: [...] } })` or per call via `getCountry(input, generate, headerNames)` / `getTimezone(input, fallback, generate, headerNames)`.
+
 ### Vinext Runtime Configuration
 
 When deploying under [Vinext](https://github.com/cloudflare/vinext) with `cloudflare:workers`, you can pass your `env` and execution context (`ctx`) directly in `setIntlConfig`:
@@ -237,6 +239,22 @@ export default setIntlConfig({
 });
 ```
 
+#### Vite Build ID Asset Plugin (`cloudflare-next-intl/vite`)
+
+When building client assets with Vite / Vinext for Cloudflare Workers, use `buildIdAsset` to emit the static `BUILD_ID` asset:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { buildIdAsset } from "cloudflare-next-intl/vite";
+
+export default defineConfig({
+    plugins: [
+        buildIdAsset(), // reads __VINEXT_SHARED_BUILD_ID or __VINEXT_BUILD_ID
+    ],
+});
+```
+
 ```tsx
 // Client Components ("use client")
 import { useLocale } from "cloudflare-next-intl/use";
@@ -450,6 +468,8 @@ export default setIntlConfig({
             // formattedMessage is a ready-to-print "[classOrMethodName] Error: ..." string
             myErrorTracker.capture(formattedMessage);
         },
+        // staleDeployPatterns: [...], // customize substrings matched by isStaleDeployError;
+        //                              // defaults to defaultStaleDeployPatterns (chunk, failed to fetch, etc)
         // overrideConsoleError: true, // route every console.error(...) call through onError too
         // ignoreConsoleErrors: [...], // defaults to defaultIgnoredConsoleErrors (this package's
         //                             // own Firebase Auth codes for expected user-input failures);
@@ -481,6 +501,37 @@ server-side resolution) on `ErrorHandlingParams` — reporting is skipped
 whenever `consent` is set and not `true`, since sending error reports to a
 third party without consent can itself be GDPR-relevant.
 
+#### Stale Deploy & Chunk Load Error Recovery
+
+When a new version of your application is deployed to Cloudflare Workers, users on older client sessions may encounter `ChunkLoadError` or failed dynamic imports when requesting outdated chunks. Use `isStaleDeployError` and `clearClientCache` in error boundaries or global error handlers to automatically recover:
+
+```typescript
+import { isStaleDeployError, clearClientCache } from "cloudflare-next-intl/errorHandling";
+
+export default function GlobalError({
+    error,
+    reset,
+}: {
+    error: Error & { digest?: string };
+    reset: () => void;
+}) {
+    useEffect(() => {
+        if (isStaleDeployError(error)) {
+            clearClientCache().then(() => {
+                window.location.reload();
+            });
+        }
+    }, [error]);
+
+    // ... render fallback UI
+}
+```
+
+- `isStaleDeployError(error: Error, patterns?: readonly string[]): boolean`: Returns `true` if the error indicates a missing chunk, failed fetch, CSS chunk failure, closed connection, corrupted RSC payload, or hydration error #412 from a stale deployment. Defaults to `defaultStaleDeployPatterns` (or patterns configured in `intl-config.ts` via `errorHandling.staleDeployPatterns`).
+- `setStaleDeployPatterns(patterns: readonly string[]): void`: Setter to update the active pattern list and pre-compute lowercased substrings for maximum runtime performance.
+- `getStaleDeployPatterns(): readonly string[]`: Returns the currently active pattern list.
+- `clearClientCache(): Promise<void>`: Best-effort cleanup that deletes all CacheStorage caches (`window.caches`), unregisters active Service Workers, and clears `sessionStorage`.
+
 ### Database (`db`)
 
 Thin Postgres/Drizzle data-access layer over a Postgres connection string

package/dist/src/config/init_config.js

@@ -1,3 +1,4 @@
+import { setStaleDeployPatterns } from '../error_handling/is_stale_deploy_error';
 // Every path this package compares against `request.nextUrl.pathname`
 // (always `/`-prefixed) must itself start with `/` — a missing leading
 // slash means `path === fa.verifyEmailPath` (and the same check for
@@ -58,5 +59,8 @@ function normalizeFirebaseAuthPaths(config) {
  * ```
  */
 export function setIntlConfig(config) {
+    if (config.errorHandling?.staleDeployPatterns) {
+        setStaleDeployPatterns(config.errorHandling.staleDeployPatterns);
+    }
     return normalizeFirebaseAuthPaths(config);
 }

package/dist/src/error_handling/clear_client_cache.d.ts

@@ -0,0 +1 @@
+export default function clearClientCache(): Promise<void>;

package/dist/src/error_handling/clear_client_cache.js

@@ -0,0 +1,18 @@
+export default async function clearClientCache() {
+    try {
+        if (typeof window !== 'undefined' && 'caches' in window && window.caches) {
+            const keys = await caches.keys();
+            await Promise.all(keys.map((key) => caches.delete(key)));
+        }
+        if (typeof navigator !== 'undefined' && 'serviceWorker' in navigator && navigator.serviceWorker) {
+            const registrations = await navigator.serviceWorker.getRegistrations();
+            await Promise.all(registrations.map((registration) => registration.unregister()));
+        }
+        if (typeof sessionStorage !== 'undefined') {
+            sessionStorage.clear();
+        }
+    }
+    catch {
+        // best-effort cleanup, ignore failures
+    }
+}

package/dist/src/error_handling/index.d.ts

@@ -7,4 +7,6 @@ export { default as installGlobalErrorOverride } from './install_global_error_ov
 export { default as stringifyUnknown } from './stringify_unknown';
 export { default as formatErrorMessage } from './format_error_message';
 export { defaultIgnoredConsoleErrors } from './default_ignored_console_errors';
+export { default as isStaleDeployError, defaultStaleDeployPatterns, setStaleDeployPatterns, getStaleDeployPatterns, } from './is_stale_deploy_error';
+export { default as clearClientCache } from './clear_client_cache';
 export type { ErrorHandlingParams, ErrorHandlingRoutingConfig } from '../types/types';

package/dist/src/error_handling/index.js

@@ -5,3 +5,5 @@ export { default as installGlobalErrorOverride } from './install_global_error_ov
 export { default as stringifyUnknown } from './stringify_unknown';
 export { default as formatErrorMessage } from './format_error_message';
 export { defaultIgnoredConsoleErrors } from './default_ignored_console_errors';
+export { default as isStaleDeployError, defaultStaleDeployPatterns, setStaleDeployPatterns, getStaleDeployPatterns, } from './is_stale_deploy_error';
+export { default as clearClientCache } from './clear_client_cache';

package/dist/src/error_handling/is_stale_deploy_error.d.ts

@@ -0,0 +1,4 @@
+export declare const defaultStaleDeployPatterns: readonly string[];
+export declare function setStaleDeployPatterns(patterns: readonly string[]): void;
+export declare function getStaleDeployPatterns(): readonly string[];
+export default function isStaleDeployError(error: Error, patterns?: readonly string[]): boolean;

package/dist/src/error_handling/is_stale_deploy_error.js

@@ -0,0 +1,31 @@
+export const defaultStaleDeployPatterns = [
+    'chunk',
+    'failed to fetch',
+    'loading css chunk',
+    'connection closed',
+    'rsc payload',
+    'minified react error #412',
+];
+let activePatterns = defaultStaleDeployPatterns;
+let activeLowercasedPatterns = defaultStaleDeployPatterns.map((p) => p.toLowerCase());
+export function setStaleDeployPatterns(patterns) {
+    activePatterns = patterns;
+    activeLowercasedPatterns = patterns.map((p) => p.toLowerCase());
+}
+export function getStaleDeployPatterns() {
+    return activePatterns;
+}
+export default function isStaleDeployError(error, patterns) {
+    if (!error)
+        return false;
+    if (error.name === 'ChunkLoadError')
+        return true;
+    const message = (error.message || '').toLowerCase();
+    const list = patterns ? patterns.map((p) => p.toLowerCase()) : activeLowercasedPatterns;
+    for (let i = 0; i < list.length; i++) {
+        if (message.includes(list[i])) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/src/types/types.d.ts

@@ -264,6 +264,13 @@ export interface ErrorHandlingRoutingConfig {
      * default entirely; pass `[]` to report everything.
      */
     ignoreConsoleErrors?: readonly string[];
+    /**
+     * Error message patterns matched by `isStaleDeployError(error)` to detect
+     * stale deploy / chunk load errors (e.g. `'chunk'`, `'failed to fetch'`,
+     * `'loading css chunk'`, `'connection closed'`, `'rsc payload'`,
+     * `'minified react error #412'`). Defaults to `defaultStaleDeployPatterns`.
+     */
+    staleDeployPatterns?: readonly string[];
     /**
      * Called with the stringified message of each `console.error(...)` call
      * (only consulted when `overrideConsoleError` is `true`), in addition to

package/dist/src/vite/build_id_asset.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function buildIdAsset(fileName?: string): Plugin;

package/dist/src/vite/build_id_asset.js

@@ -0,0 +1,14 @@
+export function buildIdAsset(fileName = "BUILD_ID") {
+    return {
+        name: "cfni:build-id-asset",
+        apply: "build",
+        generateBundle() {
+            if (this.environment?.name !== "client")
+                return;
+            const buildId = process.env.__VINEXT_SHARED_BUILD_ID ?? process.env.__VINEXT_BUILD_ID;
+            if (!buildId)
+                return;
+            this.emitFile({ type: "asset", fileName, source: buildId });
+        },
+    };
+}

package/llms.txt

@@ -27,6 +27,11 @@ 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` — `buildIdAsset(fileName?)`: Vite plugin to emit the client `BUILD_ID` asset (from `__VINEXT_SHARED_BUILD_ID` or `__VINEXT_BUILD_ID`) during build in Vinext/Vite environments.
+- `./errorHandling` — error reporting & stale deploy recovery barrel: `reportError`, `withErrorHandling`, `installConsoleErrorOverride`, `installGlobalErrorOverride`, `stringifyUnknown`, `formatErrorMessage`, `defaultIgnoredConsoleErrors`, `createServerErrorAction`, `isStaleDeployError`, `defaultStaleDeployPatterns`, `setStaleDeployPatterns`, `getStaleDeployPatterns`, `clearClientCache`.
+- `./isStaleDeployError` — `isStaleDeployError(error, patterns?)`, `setStaleDeployPatterns(patterns)`, `getStaleDeployPatterns()`: detector returning `true` for version skew / chunk load / hydration errors (ChunkLoadError, failed to fetch, loading CSS chunk, connection closed, RSC payload failure, minified error #412) with fast pre-lowercased pattern cache and intl-config integration (`errorHandling.staleDeployPatterns`).
+- `./clearClientCache` — `clearClientCache()`: async helper wiping `window.caches`, unregistering service workers, and clearing `sessionStorage` for recovering from stale deployments.
+- `./createServerErrorAction` — `createServerErrorAction(action, config)`: wrapper for server actions with standardized error reporting.
 
 ## `firebaseAuth*` subpaths (require `firebaseAuth` set on your `RoutingConfig`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.8.41",
+  "version": "0.8.43",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -190,6 +190,14 @@
       "types": "./dist/src/error_handling/create_server_error_action.d.ts",
       "import": "./dist/src/error_handling/create_server_error_action.js"
     },
+    "./isStaleDeployError": {
+      "types": "./dist/src/error_handling/is_stale_deploy_error.d.ts",
+      "import": "./dist/src/error_handling/is_stale_deploy_error.js"
+    },
+    "./clearClientCache": {
+      "types": "./dist/src/error_handling/clear_client_cache.d.ts",
+      "import": "./dist/src/error_handling/clear_client_cache.js"
+    },
     "./db": {
       "types": "./dist/src/db/index.d.ts",
       "import": "./dist/src/db/index.js"
@@ -209,6 +217,10 @@
     "./dbSchema": {
       "types": "./dist/src/db/schema.d.ts",
       "import": "./dist/src/db/schema.js"
+    },
+    "./vite": {
+      "types": "./dist/src/vite/build_id_asset.d.ts",
+      "import": "./dist/src/vite/build_id_asset.js"
     }
   },
   "scripts": {
@@ -264,11 +276,15 @@
   "peerDependencies": {
     "next": ">=12.0.0",
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || >=19.0.0-rc <19.0.0 || ^19.0.0",
-    "typescript": ">=5.0.0"
+    "typescript": ">=5.0.0",
+    "vite": ">=6"
   },
   "peerDependenciesMeta": {
     "typescript": {
       "optional": true
+    },
+    "vite": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -292,6 +308,7 @@
     "tsup": "^8.5.1",
     "typescript": "^5.5.3",
     "typescript-eslint": "^8.33.1",
+    "vite": "^7.0.0",
     "vitest": "^3.0.8"
   }
 }