cloudflare-next-intl 0.8.44 → 0.8.46

package/README.md

@@ -532,6 +532,34 @@ export default function GlobalError({
 - `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`.
 
+For a ready-made recovery flow (recommended over wiring `isStaleDeployError` + `clearClientCache` by hand), use the `useStaleDeployRecovery` hook:
+
+```typescript
+'use client';
+
+import { useStaleDeployRecovery } from "cloudflare-next-intl/errorHandling";
+
+export default function GlobalError({
+    error,
+    reset,
+}: {
+    error: Error & { digest?: string };
+    reset: () => void;
+}) {
+    // Optionally pass a server action to clear server-side cookies/cache
+    // before the reload; runs alongside clearClientCache() and any
+    // rejection is ignored (best-effort).
+    const isRecovering = useStaleDeployRecovery(error /*, clearServerCookies */);
+
+    if (isRecovering) return <LoadingIndicator />;
+
+    // ... render your normal error UI
+}
+```
+
+- `useStaleDeployRecovery(error: Error, onRecover?: () => Promise<unknown>, delayMs = 5000): boolean`: Detects a stale-deploy error via `isStaleDeployError` and, **once per build id**, waits `delayMs`, runs `onRecover` (if provided) and `clearClientCache` in parallel, then reloads the page. The build id is read from `localStorage['buildId']` (set by `IntlHelperScript`'s `BUILD_ID` check) and a `sessionStorage` marker records which build id already spent its reload, so a repeat failure on the same build falls through to `false` (render your normal error UI) instead of reloading forever. A redeploy changes the build id and re-arms exactly one more attempt.
+- `shouldRecoverFromStaleDeploy(error: Error, buildId: string, marker: string | null): boolean`: The pure predicate behind the hook, exported for testing.
+
 ### Database (`db`)
 
 Thin Postgres/Drizzle data-access layer over a Postgres connection string

package/dist/src/error_handling/default_ignored_console_errors.js

@@ -34,6 +34,8 @@ export const defaultIgnoredConsoleErrors = [
     "FirebaseServerApp authIdToken is invalid: the token has expired.",
     "failed Error: Database is closing/hidden",
     'Failed to fetch RSC payload',
+    'The above error occurred in a React component',
+    'The connection to the page was unexpectedly closed',
     ...(process.env.NODE_ENV === 'development'
         ? ['A DurableObjectNamespace in the config referenced the class "DOQueueHandler", but no such Durable Object class is exported from the worker. Please make sure the class name matches,']
         : []),

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

@@ -9,4 +9,5 @@ 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 { default as useStaleDeployRecovery, shouldRecoverFromStaleDeploy } from './use_stale_deploy_recovery';
 export type { ErrorHandlingParams, ErrorHandlingRoutingConfig } from '../types/types';

package/dist/src/error_handling/index.js

@@ -7,3 +7,4 @@ 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 { default as useStaleDeployRecovery, shouldRecoverFromStaleDeploy } from './use_stale_deploy_recovery';

package/dist/src/error_handling/is_stale_deploy_error.js

@@ -5,6 +5,8 @@ export const defaultStaleDeployPatterns = [
     'connection closed',
     'rsc payload',
     'minified react error #412',
+    'the above error occurred in a react component',
+    'the connection to the page was unexpectedly closed',
 ];
 let activePatterns = defaultStaleDeployPatterns;
 let activeLowercasedPatterns = defaultStaleDeployPatterns.map((p) => p.toLowerCase());

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

@@ -0,0 +1,10 @@
+export declare function shouldRecoverFromStaleDeploy(error: Error, buildId: string, marker: string | null): boolean;
+/**
+ * Detects a stale-deploy error and, once per build id, silently clears client
+ * caches and reloads after `delayMs`. Returns whether a reload is pending so
+ * the caller can render a loading state instead of the error UI while it
+ * waits. `onRecover` runs before the reload (e.g. to clear server cookies via
+ * a server action) and its rejection is ignored — cache clearing is
+ * best-effort.
+ */
+export default function useStaleDeployRecovery(error: Error, onRecover?: () => Promise<unknown>, delayMs?: number): boolean;

package/dist/src/error_handling/use_stale_deploy_recovery.js

@@ -0,0 +1,60 @@
+'use client';
+import { useEffect, useState } from 'react';
+import isStaleDeployError from './is_stale_deploy_error';
+import clearClientCache from './clear_client_cache';
+const RECOVERY_RELOAD_KEY = 'stale-deploy-recovery-reloaded';
+const BUILD_ID_KEY = 'buildId';
+function currentBuildId() {
+    try {
+        return localStorage.getItem(BUILD_ID_KEY) ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+// One silent reload per deployment. The marker carries the build id the reload
+// was spent on, so a redeploy re-arms exactly one more attempt while a repeat
+// failure on the same build falls through to the caller's error UI instead of
+// spinning forever.
+export function shouldRecoverFromStaleDeploy(error, buildId, marker) {
+    return isStaleDeployError(error) && marker !== buildId;
+}
+function canRecover(error) {
+    if (typeof window === 'undefined')
+        return false;
+    try {
+        return shouldRecoverFromStaleDeploy(error, currentBuildId(), sessionStorage.getItem(RECOVERY_RELOAD_KEY));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detects a stale-deploy error and, once per build id, silently clears client
+ * caches and reloads after `delayMs`. Returns whether a reload is pending so
+ * the caller can render a loading state instead of the error UI while it
+ * waits. `onRecover` runs before the reload (e.g. to clear server cookies via
+ * a server action) and its rejection is ignored — cache clearing is
+ * best-effort.
+ */
+export default function useStaleDeployRecovery(error, onRecover, delayMs = 5000) {
+    const [recovering] = useState(() => canRecover(error));
+    useEffect(() => {
+        if (!recovering)
+            return;
+        const buildId = currentBuildId();
+        const timeout = setTimeout(() => {
+            Promise.all([onRecover?.().catch(() => undefined), clearClientCache().catch(() => undefined)])
+                .finally(() => {
+                try {
+                    sessionStorage.setItem(RECOVERY_RELOAD_KEY, buildId);
+                }
+                catch { /* storage unavailable */ }
+                window.location.reload();
+            });
+        }, delayMs);
+        return () => clearTimeout(timeout);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [recovering]);
+    return recovering;
+}

package/llms.txt

@@ -28,9 +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`.
+- `./errorHandling` — error reporting & stale deploy recovery barrel: `reportError`, `withErrorHandling`, `installConsoleErrorOverride`, `installGlobalErrorOverride`, `stringifyUnknown`, `formatErrorMessage`, `defaultIgnoredConsoleErrors`, `createServerErrorAction`, `isStaleDeployError`, `defaultStaleDeployPatterns`, `setStaleDeployPatterns`, `getStaleDeployPatterns`, `clearClientCache`, `useStaleDeployRecovery`, `shouldRecoverFromStaleDeploy`.
 - `./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.
+- `useStaleDeployRecovery(error, onRecover?, delayMs?)` (client hook, in `./errorHandling`) — once per build id (`localStorage['buildId']`, `sessionStorage` marker), waits `delayMs` (default 5000ms), runs optional `onRecover()` + `clearClientCache()` in parallel, then `window.location.reload()`. Returns whether a reload is pending, so caller renders a loading state instead of error UI. `shouldRecoverFromStaleDeploy(error, buildId, marker)` is the pure predicate.
 - `./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.44",
+  "version": "0.8.46",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",