cloudflare-next-intl 0.8.42 → 0.8.44

package/README.md

@@ -468,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);
@@ -499,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/client/hooks/use_path_name.js

@@ -13,6 +13,9 @@ import { useLocale } from "./client_hooks";
 export default function usePathname() {
     const pathname = nextUsePathname();
     const locale = useLocale();
+    if (!pathname) {
+        return '/';
+    }
     const path = pathname.replace(`/${locale}`, '');
     if (path) {
         return path;

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/cookie_consent/client/cookie_consent_provider.js

@@ -116,7 +116,7 @@ export default function CookieConsentProvider({ requiresConsent = true, children
     // `pathname` still carries the locale prefix (e.g. `/de/privacy-policy`),
     // so match on a trailing segment rather than strict equality.
     useEffect(() => {
-        if (privacyPolicyUpdated && privacyPolicyPath !== false && pathname.endsWith(privacyPolicyPath)) {
+        if (privacyPolicyUpdated && privacyPolicyPath !== false && pathname?.endsWith(privacyPolicyPath)) {
             acknowledgePrivacyPolicyUpdate();
         }
     }, [pathname, privacyPolicyUpdated, privacyPolicyPath, acknowledgePrivacyPolicyUpdate]);

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/llms.txt

@@ -28,6 +28,10 @@ other subpath can be used.
 - `./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.42",
+  "version": "0.8.44",
   "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"