cloudflare-next-intl 0.9.52 → 0.9.54

package/README.md

@@ -690,7 +690,9 @@ through `@intl-config`.
 
 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.
 
-`IntlHelperScript` renders an early-catch `<script>` (production only, id `stale-deploy-early-catch`) that runs before hydration and listens for `window.error`/`unhandledrejection` events matching the same patterns as `isStaleDeployError` (inlined as JSON, so it stays in sync with `staleDeployPatterns` config), then force-reloads once per build id (throttled to once per 15s so a later build-id marker can re-arm recovery instead of being blocked indefinitely). It also listens for `error` events during the capture phase to catch resource-load failures (a chunk `<script>`/`<link>` 404ing or served with a disallowed MIME type), which fire a non-bubbling, message-less `error` event on the element itself rather than surfacing as a catchable message. This covers the case a React-level recovery (`useStaleDeployRecovery` below) cannot: when the chunk that failed to load is part of your own error boundary/global-error bundle, React never gets a chance to render the recovery UI. Both layers share the same `sessionStorage['stale-deploy-recovery-reloaded']` marker keyed by build id, so they can't double-reload each other. No setup beyond rendering `<IntlHelperScript />` is required.
+`IntlHelperScript` renders an early-catch `<script>` (production only, id `stale-deploy-early-catch`) that runs before hydration and listens for `window.error`/`unhandledrejection` events matching the same patterns as `isStaleDeployError` (inlined as JSON, so it stays in sync with `staleDeployPatterns` config), then force-reloads (throttled to once per 15s, capped at 2 attempts per build id — a 3rd stale-deploy error for the same build id falls through instead of reloading again; the count resets once a new build id is seen). It also listens for `error` events during the capture phase to catch resource-load failures (a same-origin chunk `<script>`/`<link>` 404ing or served with a disallowed MIME type), which fire a non-bubbling, message-less `error` event on the element itself rather than surfacing as a catchable message; a failed third-party resource (analytics, reCAPTCHA, etc.) is ignored, since only the app's own build output can break its module graph. This covers the case a React-level recovery (`useStaleDeployRecovery` below) cannot: when the chunk that failed to load is part of your own error boundary/global-error bundle, React never gets a chance to render the recovery UI. Both layers share the same `sessionStorage['stale-deploy-recovery-reloaded']` marker keyed by build id, so they can't double-reload each other. No setup beyond rendering `<IntlHelperScript />` is required.
+
+`installGlobalErrorOverride` (used internally by error reporting setup) also reports these same-tree resource-load failures — a failed `script`/`link` load is reported via `reportError` instead of being silently dropped, since the browser gives it no bubbling event or message to catch any other way.
 
 For errors that don't crash the module graph itself (a normal thrown error reaching an error boundary), use `isStaleDeployError` and `clearClientCache` in error boundaries or global error handlers to automatically recover:
 

package/dist/src/error_handling/install_global_error_override.js

@@ -16,6 +16,22 @@ export default function installGlobalErrorOverride(config) {
             isClient: true,
         });
     });
+    window.addEventListener('error', (event) => {
+        const el = event.target;
+        if (!el || el === window)
+            return;
+        const tag = el.tagName?.toLowerCase();
+        if (tag !== 'script' && tag !== 'link')
+            return;
+        const src = el.src || el.href;
+        if (!src)
+            return;
+        void reportError(config, {
+            error: `Failed to load ${tag} resource: ${src}`,
+            classOrMethodName: 'Global Resource Error Handler',
+            isClient: true,
+        });
+    }, true);
     window.addEventListener('unhandledrejection', (event) => {
         void reportError(config, {
             error: event.reason,

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

@@ -1,4 +1,4 @@
 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, reloadTime?: number | null, now?: number, throttleMs?: number): boolean;
+export declare function shouldRecoverFromStaleDeploy(error: unknown, buildId: string, marker: string | null, recentBuild?: boolean, reloadTime?: number | null, now?: number, throttleMs?: number, attempts?: number, maxAttempts?: number): boolean;
 export declare function performCacheBustReload(): void;
 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.js';
 import clearClientCache from './clear_client_cache.js';
 const RECOVERY_RELOAD_KEY = 'stale-deploy-recovery-reloaded';
 const RECOVERY_TIME_KEY = 'stale-deploy-recovery-time';
+const RECOVERY_COUNT_KEY = 'stale-deploy-recovery-count';
+const MAX_RECOVERY_ATTEMPTS = 2;
 const BUILD_ID_KEY = 'buildId';
 const BUILD_ID_SET_AT_KEY = 'buildIdSetAt';
 const RECENT_BUILD_WINDOW_MS = 60000;
@@ -28,16 +30,33 @@ function buildIdSetAt() {
 export function isRecentBuild(setAt, now, windowMs = RECENT_BUILD_WINDOW_MS) {
     return setAt !== null && now - setAt < windowMs;
 }
-export function shouldRecoverFromStaleDeploy(error, buildId, marker, recentBuild = false, reloadTime = null, now = Date.now(), throttleMs = RELOAD_THROTTLE_MS) {
+export function shouldRecoverFromStaleDeploy(error, buildId, marker, recentBuild = false, reloadTime = null, now = Date.now(), throttleMs = RELOAD_THROTTLE_MS, attempts = 0, maxAttempts = MAX_RECOVERY_ATTEMPTS) {
     if (!isStaleDeployError(error))
         return false;
     const isRecentlyReloaded = reloadTime !== null && now - reloadTime < throttleMs;
     const isSameBuildMarker = marker !== null && marker !== '' && (buildId === 'unknown' || marker === buildId);
+    if (isSameBuildMarker && attempts >= maxAttempts) {
+        return false;
+    }
     if (isSameBuildMarker && isRecentlyReloaded && !recentBuild) {
         return false;
     }
     return true;
 }
+function currentAttempts(buildId, marker) {
+    if (marker === null || marker === '')
+        return 0;
+    if (buildId !== 'unknown' && marker !== buildId)
+        return 0;
+    try {
+        const raw = sessionStorage.getItem(RECOVERY_COUNT_KEY);
+        const parsed = raw ? Number(raw) : 0;
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+    }
+    catch {
+        return 0;
+    }
+}
 function canRecover(error) {
     if (typeof window === 'undefined')
         return false;
@@ -48,7 +67,8 @@ function canRecover(error) {
         const marker = sessionStorage.getItem(RECOVERY_RELOAD_KEY);
         const isRecent = isRecentBuild(buildIdSetAt(), Date.now());
         const isStale = isStaleDeployError(error);
-        const result = shouldRecoverFromStaleDeploy(error, bId, marker, isRecent, reloadTime, Date.now());
+        const attempts = currentAttempts(bId, marker);
+        const result = shouldRecoverFromStaleDeploy(error, bId, marker, isRecent, reloadTime, Date.now(), RELOAD_THROTTLE_MS, attempts);
         console.warn('[useStaleDeployRecovery]', {
             error,
             isStale,
@@ -56,6 +76,7 @@ function canRecover(error) {
             marker,
             isRecent,
             reloadTime,
+            attempts,
             result,
         });
         return result;
@@ -89,7 +110,10 @@ export default function useStaleDeployRecovery(error, onRecover, delayMs = 1000)
             Promise.all([initialOnRecover?.().catch(() => undefined), clearClientCache().catch(() => undefined)])
                 .finally(() => {
                 try {
+                    const marker = sessionStorage.getItem(RECOVERY_RELOAD_KEY);
+                    const spent = currentAttempts(buildId, marker);
                     sessionStorage.setItem(RECOVERY_RELOAD_KEY, buildId);
+                    sessionStorage.setItem(RECOVERY_COUNT_KEY, String(spent + 1));
                     sessionStorage.setItem(RECOVERY_TIME_KEY, String(Date.now()));
                 }
                 catch { }

package/dist/src/locale_params_check/check_locale_params.js

@@ -1,10 +1,11 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { detectLocaleParams } from './detect_locale_params.js';
-import { insertLocaleParamsSignature, insertLocaleParamsBody, ensureLocaleInParamsType, addParamsPropToExistingDestructure, ensureSetLocaleImport } from './insert_locale_params.js';
+import { insertLocaleParamsSignature, insertLocaleParamsBody, ensureLocaleInParamsType, addParamsPropToExistingDestructure, ensureSetLocaleImport, wrapSyncDefaultExportWithParams, extractParamsPromiseType } from './insert_locale_params.js';
 import { findLocaleScopedFiles } from './find_locale_scoped_files.js';
 import { deriveRoute, makePageLabeler } from '../dynamic_pages_check/derive_page_label.js';
 const ZERO_ARG_DEFAULT_EXPORT = /export\s+default\s+(async\s+)?function\s+[A-Za-z_$][\w$]*\s*\(\s*\)/;
+const SYNC_DEFAULT_EXPORT = /export\s+default\s+function\s+[A-Za-z_$][\w$]*\s*\(/;
 const LEGEND = '✓ Set up   + Added   ? Needs manual edit   · Skipped';
 function actionGlyph(action) {
     switch (action) {
@@ -76,6 +77,18 @@ export async function checkLocaleParams(options, io = {}) {
             reports.push({ file, action: 'would-add-locale-params' });
             continue;
         }
+        const isSyncDefaultExport = !detection.hasInlineDestructure && SYNC_DEFAULT_EXPORT.test(source);
+        if (isSyncDefaultExport && (isZeroArg || canAddParamsKey || canReuseExistingParams)) {
+            const existingParamsType = canReuseExistingParams ? extractParamsPromiseType(source) ?? undefined : undefined;
+            const wrapped = wrapSyncDefaultExportWithParams(source, localeParam, existingParamsType);
+            if (wrapped === source) {
+                reports.push({ file, action: 'needs-manual-edit' });
+                continue;
+            }
+            writeFile(file, ensureSetLocaleImport(wrapped));
+            reports.push({ file, action: 'added-locale-params' });
+            continue;
+        }
         let updated = source;
         if (isZeroArg) {
             updated = insertLocaleParamsSignature(updated, localeParam);

package/dist/src/locale_params_check/insert_locale_params.d.ts

@@ -1,5 +1,7 @@
 export declare function insertLocaleParamsSignature(sourceText: string, localeParam: string): string;
+export declare function wrapSyncDefaultExportWithParams(sourceText: string, localeParam: string, existingParamsType?: string): string;
 export declare function addParamsPropToExistingDestructure(sourceText: string, localeParam: string): string;
 export declare function insertLocaleParamsBody(sourceText: string, localeParam: string, hasInlineDestructure: boolean): string;
+export declare function extractParamsPromiseType(sourceText: string): string | null;
 export declare function ensureLocaleInParamsType(sourceText: string, localeParam: string): string;
 export declare function ensureSetLocaleImport(sourceText: string): string;

package/dist/src/locale_params_check/insert_locale_params.js

@@ -18,7 +18,134 @@ export function insertLocaleParamsSignature(sourceText, localeParam) {
     const replacement = `({ params }: {\n    params: Promise<{ ${localeParam}: Language }>;\n})`;
     return sourceText.slice(0, parensStart) + replacement + sourceText.slice(parensEnd);
 }
+const SYNC_DEFAULT_EXPORT_FUNCTION = /export\s+default\s+function\s+([A-Za-z_$][\w$]*)\s*\(/;
+function findUnusedContentName(sourceText, baseName) {
+    let candidate = `${baseName}ContentCloudflareNextIntl`;
+    let suffix = 2;
+    while (new RegExp(`\\b${candidate}\\b`).test(sourceText)) {
+        candidate = `${baseName}ContentCloudflareNextIntl${suffix}`;
+        suffix += 1;
+    }
+    return candidate;
+}
 const DEFAULT_EXPORT_FUNCTION_OPEN_PAREN = /export\s+default\s+(?:async\s+)?function\s+[A-Za-z_$][\w$]*\s*\(/;
+function findParamListSpan(sourceText) {
+    const openParenMatch = DEFAULT_EXPORT_FUNCTION_OPEN_PAREN.exec(sourceText);
+    if (openParenMatch === null)
+        return null;
+    const start = openParenMatch.index + openParenMatch[0].length - 1;
+    let depth = 0;
+    for (let i = start; i < sourceText.length; i++) {
+        if (sourceText[i] === '(')
+            depth++;
+        else if (sourceText[i] === ')') {
+            depth--;
+            if (depth === 0)
+                return { start, end: i + 1 };
+        }
+    }
+    return null;
+}
+function destructuredKeyNames(inner) {
+    const names = [];
+    let depth = 0;
+    let start = 0;
+    const parts = [];
+    for (let i = 0; i <= inner.length; i++) {
+        const char = inner[i];
+        if (i === inner.length || (char === ',' && depth === 0)) {
+            parts.push(inner.slice(start, i));
+            start = i + 1;
+            continue;
+        }
+        if (char === '{' || char === '(' || char === '[')
+            depth++;
+        else if (char === '}' || char === ')' || char === ']')
+            depth--;
+    }
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (trimmed === '' || trimmed.startsWith('...'))
+            continue;
+        const key = trimmed.split(':')[0].split('=')[0].trim();
+        if (/^[A-Za-z_$][\w$]*$/.test(key))
+            names.push(key);
+    }
+    return names;
+}
+export function wrapSyncDefaultExportWithParams(sourceText, localeParam, existingParamsType) {
+    const nameMatch = SYNC_DEFAULT_EXPORT_FUNCTION.exec(sourceText);
+    if (nameMatch === null)
+        return sourceText;
+    const name = nameMatch[1];
+    const paramList = findParamListSpan(sourceText);
+    if (paramList === null)
+        return sourceText;
+    const bodyStart = findFunctionBodyStart(sourceText);
+    if (bodyStart === null)
+        return sourceText;
+    const bodyEnd = findMatchingBraceEnd(sourceText, bodyStart - 1);
+    if (bodyEnd === null)
+        return sourceText;
+    const contentName = findUnusedContentName(sourceText, name);
+    const originalParams = sourceText.slice(paramList.start, paramList.end);
+    const originalBody = sourceText.slice(bodyStart, bodyEnd - 1);
+    let forwardKeys = [];
+    let forwardKeyTypes = [];
+    if (originalParams !== '()') {
+        const openBrace = originalParams.indexOf('{');
+        if (openBrace === -1)
+            return sourceText;
+        const keysEnd = findMatchingBraceEnd(originalParams, openBrace);
+        if (keysEnd === null)
+            return sourceText;
+        forwardKeys = destructuredKeyNames(originalParams.slice(openBrace + 1, keysEnd - 1));
+        let j = keysEnd;
+        while (j < originalParams.length && /\s/.test(originalParams[j]))
+            j++;
+        if (originalParams[j] === ':') {
+            j++;
+            while (j < originalParams.length && /\s/.test(originalParams[j]))
+                j++;
+            if (originalParams[j] === '{') {
+                const typeEnd = findMatchingBraceEnd(originalParams, j);
+                if (typeEnd !== null) {
+                    const typeBody = originalParams.slice(j + 1, typeEnd - 1).trim();
+                    forwardKeyTypes = typeBody === '' ? [] : typeBody.split(';').map((s) => s.trim()).filter(Boolean);
+                }
+            }
+        }
+    }
+    const otherForwardKeys = forwardKeys.filter((key) => key !== 'params');
+    const otherForwardKeyTypes = forwardKeyTypes.filter((type) => !/^params\s*:/.test(type));
+    const contentFunction = `function ${contentName}${originalParams} {${originalBody}}`;
+    const alreadyHasLocaleParam = existingParamsType !== undefined && new RegExp(`\\b${localeParam}\\b`).test(existingParamsType);
+    const wrapperParamsType = existingParamsType === undefined
+        ? `${localeParam}: Language`
+        : alreadyHasLocaleParam
+            ? existingParamsType
+            : `${existingParamsType.replace(/;?\s*$/, '')}; ${localeParam}: Language`;
+    const wrapperSignature = otherForwardKeys.length === 0 ? `{ params }` : `{ ${otherForwardKeys.join(', ')}, params }`;
+    const forwardedJsx = forwardKeys.map((key) => (key === 'params' ? ` params={params}` : ` ${key}={${key}}`)).join('');
+    const forwardedTypeLines = otherForwardKeyTypes.map((type) => `    ${type.replace(/;?\s*$/, '')};`);
+    const wrapperFunction = [
+        `// Auto-inserted by cloudflare-next-intl's checkLocaleParams (mode: "fix") — `
+            + `"${name}" was split into this async wrapper plus the sync "${contentName}" above `
+            + `it (see that function's own body, unchanged) so \`await params\` never lands in a `
+            + `function this scan didn't confirm was safe to make async. To opt this file out on a `
+            + `later run, pass it in checkLocaleParams' \`skip\` list instead of hand-editing here.`,
+        `export default async function ${name}(${wrapperSignature}: {`,
+        ...forwardedTypeLines,
+        `    params: Promise<{ ${wrapperParamsType} }>;`,
+        `}) {`,
+        `    const { ${localeParam} } = await params;`,
+        `    setLocale(${localeParam});`,
+        ``,
+        `    return <${contentName}${forwardedJsx} />;`,
+        `}`,
+    ].join('\n');
+    return sourceText.slice(0, nameMatch.index) + contentFunction + '\n\n' + wrapperFunction + sourceText.slice(bodyEnd);
+}
 function findMatchingBraceEnd(code, openBraceIndex) {
     let depth = 0;
     for (let i = openBraceIndex; i < code.length; i++) {
@@ -90,6 +217,9 @@ export function insertLocaleParamsBody(sourceText, localeParam, hasInlineDestruc
     return sourceText.slice(0, bodyStart) + line + sourceText.slice(bodyStart);
 }
 const PARAMS_PROMISE_TYPE = /params\s*:\s*Promise<\{([^}]*)\}>/;
+export function extractParamsPromiseType(sourceText) {
+    return PARAMS_PROMISE_TYPE.exec(sourceText)?.[1]?.trim() ?? null;
+}
 export function ensureLocaleInParamsType(sourceText, localeParam) {
     const match = PARAMS_PROMISE_TYPE.exec(sourceText);
     if (match === null)

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

@@ -18,6 +18,8 @@ export default function HelperScript() {
                 var patterns = ${JSON.stringify(defaultStaleDeployPatterns)};
                 var key = 'stale-deploy-recovery-reloaded';
                 var timeKey = 'stale-deploy-recovery-time';
+                var countKey = 'stale-deploy-recovery-count';
+                var maxAttempts = 2;
                 var throttleMs = 15000;
                 var attemptedThisLoad = false;
                 function isStale(msg) {
@@ -39,12 +41,27 @@ export default function HelperScript() {
                         var lastRaw = sessionStorage.getItem(timeKey);
                         var last = lastRaw ? Number(lastRaw) : null;
                         var throttled = last !== null && (Date.now() - last) < throttleMs;
-                        if (marker === buildId && throttled) {
-                            console.warn('[StaleDeploy early-catch] Skipping reload, already attempted for buildId:', buildId);
+                        // Attempts are counted per build id: the 1st and 2nd
+                        // page load may each recover, the 3rd falls through to
+                        // the error UI. A new deploy resets the count.
+                        var sameBuild = marker === buildId;
+                        var attempts = 0;
+                        if (sameBuild) {
+                            var rawCount = sessionStorage.getItem(countKey);
+                            attempts = rawCount ? Number(rawCount) : 0;
+                            if (!(attempts >= 0)) attempts = 0;
+                        }
+                        if (sameBuild && attempts >= maxAttempts) {
+                            console.warn('[StaleDeploy early-catch] Skipping reload, attempts exhausted for buildId:', buildId, attempts);
+                            return;
+                        }
+                        if (sameBuild && throttled) {
+                            console.warn('[StaleDeploy early-catch] Skipping reload, throttled for buildId:', buildId);
                             return;
                         }
                         attemptedThisLoad = true;
                         sessionStorage.setItem(key, buildId);
+                        sessionStorage.setItem(countKey, String(attempts + 1));
                         sessionStorage.setItem(timeKey, String(Date.now()));
                         try {
                             if (document.documentElement) {
@@ -79,6 +96,12 @@ export default function HelperScript() {
                         if (tag !== 'script' && tag !== 'link') return;
                         var src = el.src || el.href || '';
                         if (!src) return;
+                        // Only our own build output can break the React module
+                        // graph. A failed third-party script (analytics,
+                        // reCAPTCHA) must never trigger a reload.
+                        var sameOrigin = false;
+                        try { sameOrigin = new URL(src, window.location.href).origin === window.location.origin; } catch (err2) { return; }
+                        if (!sameOrigin) return;
                         recover('chunk resource failed to load: ' + src, 'resource-error');
                     } catch (err) {}
                 }, true);

package/package.json

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