cloudflare-next-intl 0.8.47 → 0.8.49

package/README.md

@@ -557,8 +557,9 @@ export default function GlobalError({
 }
 ```
 
-- `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.
+- `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. **Exception:** if the build id was written within the last 60 seconds (`localStorage['buildIdSetAt']`, also set by `IntlHelperScript`), the hook recovers anyway — a stale-deploy error moments after adopting a new build is the deploy still settling, not a real failure, so the one-reload cap is bypassed for that window.
+- `shouldRecoverFromStaleDeploy(error: Error, buildId: string, marker: string | null, recentBuild = false): boolean`: The pure predicate behind the hook, exported for testing.
+- `isRecentBuild(setAt: number | null, now: number, windowMs = 60000): boolean`: Whether `setAt` (typically `buildIdSetAt`) falls within `windowMs` of `now`.
 
 ### Database (`db`)
 

package/dist/src/error_handling/default_ignored_console_errors.js

@@ -32,6 +32,7 @@ export const defaultIgnoredConsoleErrors = [
     'The `punycode` module is deprecated. Please use a userland alternative instead.',
     'failed to pipe response',
     "FirebaseServerApp authIdToken is invalid: the token has expired.",
+    "FirebaseServerApp appCheckToken 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',

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

@@ -1,4 +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;
+export default function isStaleDeployError(error: unknown, patterns?: readonly string[]): boolean;

package/dist/src/error_handling/is_stale_deploy_error.js

@@ -18,8 +18,18 @@ export function getStaleDeployPatterns() {
     return activePatterns;
 }
 export default function isStaleDeployError(error, patterns) {
+    // A stale build can leave the caught value itself missing — e.g. an
+    // aborted RSC stream reaching a client component as `undefined` rather
+    // than a real Error (seen as "Global Error undefined ... The above error
+    // occurred in a React component" in the console, with no message to
+    // pattern-match on). Treat exactly `undefined` as stale-deploy; a normal
+    // thrown error is never `undefined`.
+    if (error === undefined)
+        return true;
     if (!error)
         return false;
+    if (!(error instanceof Error))
+        return false;
     if (error.name === 'ChunkLoadError')
         return true;
     const message = (error.message || '').toLowerCase();

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

@@ -1,4 +1,13 @@
-export declare function shouldRecoverFromStaleDeploy(error: Error, buildId: string, marker: string | null): boolean;
+/**
+ * True when this build id was written within the last `windowMs` — i.e. the
+ * client just picked up a new deploy (via `IntlHelperScript`'s BUILD_ID
+ * check). A stale-deploy error in that window is the deploy itself still
+ * settling (new chunks, in-flight RSC requests against the old build), not a
+ * failure a reload can't fix — so it recovers even on a build id the reload
+ * marker already covers.
+ */
+export declare function isRecentBuild(setAt: number | null, now: number, windowMs?: number): boolean;
+export declare function shouldRecoverFromStaleDeploy(error: unknown, buildId: string, marker: string | null, recentBuild?: boolean): 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
@@ -7,4 +16,4 @@ export declare function shouldRecoverFromStaleDeploy(error: Error, buildId: stri
  * 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;
+export default function useStaleDeployRecovery(error: unknown, onRecover?: () => Promise<unknown>, delayMs?: number): boolean;

package/dist/src/error_handling/use_stale_deploy_recovery.js

@@ -4,6 +4,8 @@ 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';
+const BUILD_ID_SET_AT_KEY = 'buildIdSetAt';
+const RECENT_BUILD_WINDOW_MS = 60000;
 function currentBuildId() {
     try {
         return localStorage.getItem(BUILD_ID_KEY) ?? 'unknown';
@@ -12,18 +14,39 @@ function currentBuildId() {
         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 buildIdSetAt() {
+    try {
+        const raw = localStorage.getItem(BUILD_ID_SET_AT_KEY);
+        return raw ? Number(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when this build id was written within the last `windowMs` — i.e. the
+ * client just picked up a new deploy (via `IntlHelperScript`'s BUILD_ID
+ * check). A stale-deploy error in that window is the deploy itself still
+ * settling (new chunks, in-flight RSC requests against the old build), not a
+ * failure a reload can't fix — so it recovers even on a build id the reload
+ * marker already covers.
+ */
+export function isRecentBuild(setAt, now, windowMs = RECENT_BUILD_WINDOW_MS) {
+    return setAt !== null && now - setAt < windowMs;
+}
+// One silent reload per deployment, UNLESS the build id was written moments
+// ago — see `isRecentBuild`. The marker carries the build id the reload was
+// spent on, so a redeploy re-arms exactly one more attempt while a repeat
+// failure well after the deploy settled falls through to the caller's error
+// UI instead of spinning forever.
+export function shouldRecoverFromStaleDeploy(error, buildId, marker, recentBuild = false) {
+    return isStaleDeployError(error) && (marker !== buildId || recentBuild);
 }
 function canRecover(error) {
     if (typeof window === 'undefined')
         return false;
     try {
-        return shouldRecoverFromStaleDeploy(error, currentBuildId(), sessionStorage.getItem(RECOVERY_RELOAD_KEY));
+        return shouldRecoverFromStaleDeploy(error, currentBuildId(), sessionStorage.getItem(RECOVERY_RELOAD_KEY), isRecentBuild(buildIdSetAt(), Date.now()));
     }
     catch {
         return false;

package/dist/src/server/components/helper_script.js

@@ -44,23 +44,9 @@ export default function HelperScript() {
 
                         if (prevBuild !== BUILD_ID) {
                             localStorage.setItem('buildId', BUILD_ID);
+                            localStorage.setItem('buildIdSetAt', String(Date.now()));
                             if(prevBuild){
-                                // Reloading while the document/RSC stream is
-                                // still downloading is the same as pressing
-                                // Stop: Firefox aborts the in-flight read and
-                                // surfaces "The connection to the page was
-                                // unexpectedly closed", which reaches React as
-                                // a caught error and renders the app's error
-                                // screen. Wait for the load to settle first.
-                                if (document.readyState === 'complete') {
-                                    window.location.reload();
-                                } else {
-                                    window.addEventListener(
-                                        'load',
-                                        function () { window.location.reload(); },
-                                        { once: true },
-                                    );
-                                }
+                                window.location.reload(true);
                             }
                         }
                     }

package/llms.txt

@@ -28,10 +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`, `useStaleDeployRecovery`, `shouldRecoverFromStaleDeploy`.
+- `./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 / 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.
+- `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. Recovers even past the one-reload cap when `localStorage['buildIdSetAt']` is <60s old (new deploy still settling). `shouldRecoverFromStaleDeploy(error, buildId, marker, recentBuild?)` and `isRecentBuild(setAt, now, windowMs?)` are the pure predicates.
 - `./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.47",
+  "version": "0.8.49",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",