cloudflare-next-intl 0.5.7 → 0.6.1

package/README.md

@@ -11,6 +11,8 @@ and Cloudflare environment.
   Components.
 - **Fast and Efficient**: Low overhead and minimal bundle size.
 - **Tree-shaking**: Properly architected for optimal tree-shaking.
+- **Error handling**: shared, opt-in `console.error` override and
+  `reportError`/`withErrorHandling` helpers, GDPR-aware (consent-gated).
 
 ## Installation
 
@@ -200,16 +202,21 @@ import { getCloudflareContext } from "@opennextjs/cloudflare";
 export default setIntlConfig({
     locales: ["en", "de"],
     defaultLocale: "en",
+    // Shared request-time resolvers — used by cookieConsent's GDPR gating
+    // below AND by error_handling's ctx.waitUntil backgrounding.
+    generate: {
+        // Pass @opennextjs/cloudflare's getCloudflareContext directly — its
+        // exact overloaded signature is accepted as-is, called internally
+        // with { async: true } (cookieConsent) or { async: false } (error_handling).
+        getCloudflareContext,
+    },
     cookieConsent: {
         privacyPolicyDate: "2026-01-01",
         // privacyPolicyPath: "/privacy-policy", // default; used by the
         // dialogs' auto-rendered link. Set false to disable that link.
         // Optional: gate the banner to GDPR-region visitors only. Omit both
-        // getters to disable country-based gating (consent always implicit).
-        // Pass @opennextjs/cloudflare's getCloudflareContext directly — its
-        // exact overloaded signature is accepted as-is, called internally
-        // with { async: true }.
-        getCloudflareContext,
+        // getCountryCode and generate.getCloudflareContext to disable
+        // country-based gating (consent always implicit).
         // gdprCountries: [...], // defaults to EU/EEA + UK + Switzerland
         // enableAnalyticsInDevMode: true, // analytics stay off in dev otherwise
         // autoWireDialogs: false, // opt out and render the dialogs yourself
@@ -246,6 +253,58 @@ const { consent, setConsent } = useCookieConsent();
 
 See [`package/src/cookie_consent/README.md`](package/src/cookie_consent/README.md) for layout, customization, and gotchas.
 
+### Error handling
+
+Every risky call this package makes internally (Cloudflare-context
+resolution, Firebase server auth, `cookieConsent.getAnalytics()`) reports
+through a shared `error_handling` submodule you can also use in your own
+app code. Enabled by default — no config needed to get the default
+`console.error`-based reporting; set `errorHandling.onError` to plug in
+your own transport (Sentry, Telegram, etc).
+
+```typescript
+// intl-config.ts
+export default setIntlConfig({
+    locales: ["en", "de"],
+    defaultLocale: "en",
+    generate: { getCloudflareContext }, // reports background via ctx.waitUntil when set
+    errorHandling: {
+        // enable: false, // fully disable reporting (errors still rethrow from withErrorHandling)
+        onError: ({ formattedMessage, error, classOrMethodName, consent }) => {
+            // formattedMessage is a ready-to-print "[classOrMethodName] Error: ..." string
+            myErrorTracker.capture(formattedMessage);
+        },
+        // 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);
+        //                             // pass [] to report everything, or your own list to replace it
+        // ignoreConsoleError: (message) => message.includes("known noisy warning"),
+    },
+});
+```
+
+Use `reportError`/`withErrorHandling` directly in your own code:
+
+```typescript
+import { reportError, withErrorHandling } from "cloudflare-next-intl/errorHandling";
+import config from "./intl-config";
+
+// Wrap a function — reports then rethrows on failure.
+const safeFetch = withErrorHandling(fetchSomething, "fetchSomething", { config });
+
+// Or report manually inside your own try/catch.
+try {
+    await riskyThing();
+} catch (error) {
+    await reportError(config, { error, classOrMethodName: "riskyThing" });
+}
+```
+
+**GDPR note:** pass `consent` (from `useCookieConsent()` or your own
+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.
+
 ## License
 
 MIT

package/dist/src/client/components/client_provider.js

@@ -4,6 +4,7 @@ import { setLocaleCache, setMessageForLocaleCache } from "../../general/cache_va
 import { createContext, useMemo } from "react";
 import dynamic from "next/dynamic";
 import config from "@intl-config";
+import installConsoleErrorOverride from "../../error_handling/install_console_error_override";
 export const LocaleContext = createContext(undefined);
 // Hoisted to module scope — calling `dynamic()` inside the component body
 // creates a brand-new component identity every render, forcing React to
@@ -20,6 +21,7 @@ const PrivacyPolicyUpdateDialog = dynamic(() => import("../../cookie_consent/cli
 export default function LocationzationClientProvider({ language, messages, initialAuthUser = null, skipAuthProvider = false, analyticsConfig, requiresConsent = true, autoWireDialogs = true, dialogProps, updateDialogProps, children }) {
     setLocaleCache(language);
     setMessageForLocaleCache(language, messages);
+    installConsoleErrorOverride(config, true);
     // `LocaleContext.Provider` stays the outermost element here — the
     // client `AuthUserProvider` (and its descendants calling
     // usePathname()/useLocale()) must render as a CHILD of it, not a

package/dist/src/cookie_consent/gdpr_countries.d.ts

@@ -1,4 +1,4 @@
-import type { CookieConsentGetCloudflareContext } from '../types/types';
+import type { CookieConsentGetCloudflareContext, ErrorHandlingRoutingConfig } from '../types/types';
 /**
  * Default `cookieConsent.gdprCountries` — EU/EEA member states (GDPR),
  * Iceland/Liechtenstein/Norway (EEA), the UK (UK-GDPR), and Switzerland
@@ -15,4 +15,4 @@ export declare const defaultGdprCountries: readonly string[];
  *   `gdprCountries` skips the banner. `getCountryCode` takes precedence
  *   over `getCloudflareContext` when both are set.
  */
-export default function resolveRequiresConsent(getCountryCode: (() => string | undefined | Promise<string | undefined>) | undefined, getCloudflareContext: CookieConsentGetCloudflareContext | undefined, gdprCountries: readonly string[] | undefined): Promise<boolean>;
+export default function resolveRequiresConsent(getCountryCode: (() => string | undefined | Promise<string | undefined>) | undefined, getCloudflareContext: CookieConsentGetCloudflareContext | undefined, gdprCountries: readonly string[] | undefined, errorHandlingConfig?: ErrorHandlingRoutingConfig): Promise<boolean>;

package/dist/src/cookie_consent/gdpr_countries.js

@@ -1,3 +1,4 @@
+import reportError from '../error_handling/report_error';
 /**
  * Default `cookieConsent.gdprCountries` — EU/EEA member states (GDPR),
  * Iceland/Liechtenstein/Norway (EEA), the UK (UK-GDPR), and Switzerland
@@ -40,12 +41,22 @@ function getGdprCountriesSet(gdprCountries) {
  *   `gdprCountries` skips the banner. `getCountryCode` takes precedence
  *   over `getCloudflareContext` when both are set.
  */
-export default async function resolveRequiresConsent(getCountryCode, getCloudflareContext, gdprCountries) {
+export default async function resolveRequiresConsent(getCountryCode, getCloudflareContext, gdprCountries, errorHandlingConfig) {
     if (!getCountryCode && !getCloudflareContext)
         return true;
-    const countryCode = getCountryCode
-        ? await getCountryCode()
-        : (await getCloudflareContext({ async: true }))?.cf?.country;
+    let countryCode;
+    if (getCountryCode) {
+        countryCode = await getCountryCode();
+    }
+    else {
+        try {
+            countryCode = (await getCloudflareContext({ async: true }))?.cf?.country;
+        }
+        catch (error) {
+            await reportError({ errorHandling: errorHandlingConfig, generate: { getCloudflareContext } }, { error, classOrMethodName: 'resolveRequiresConsent' });
+            return true;
+        }
+    }
     if (typeof countryCode !== 'string' || !countryCode)
         return true;
     return getGdprCountriesSet(gdprCountries).has(countryCode);

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

@@ -0,0 +1,13 @@
+/**
+ * Firebase Auth error codes this package's own `createLoginAction`/
+ * `createSignUpAction`/`createForgotPasswordAction` already catch and
+ * translate into a localized message (see
+ * `firebase_auth/error_messages/firebase_auth_error_helper.ts`) — expected
+ * user-input failures (wrong password, email already in use, etc.), not
+ * bugs. They never reach `console.error`/`reportError` through this
+ * package's own code; this list exists as defense-in-depth for consumers
+ * whose own code logs one of these codes directly. Passing your own
+ * `ignoreConsoleError` array replaces this default entirely — pass `[]` to
+ * report everything.
+ */
+export declare const defaultIgnoredConsoleErrors: readonly string[];

package/dist/src/error_handling/default_ignored_console_errors.js

@@ -0,0 +1,27 @@
+/**
+ * Firebase Auth error codes this package's own `createLoginAction`/
+ * `createSignUpAction`/`createForgotPasswordAction` already catch and
+ * translate into a localized message (see
+ * `firebase_auth/error_messages/firebase_auth_error_helper.ts`) — expected
+ * user-input failures (wrong password, email already in use, etc.), not
+ * bugs. They never reach `console.error`/`reportError` through this
+ * package's own code; this list exists as defense-in-depth for consumers
+ * whose own code logs one of these codes directly. Passing your own
+ * `ignoreConsoleError` array replaces this default entirely — pass `[]` to
+ * report everything.
+ */
+export const defaultIgnoredConsoleErrors = [
+    'auth/invalid-email',
+    'auth/user-disabled',
+    'auth/user-not-found',
+    'auth/wrong-password',
+    'auth/invalid-credential',
+    'auth/email-already-in-use',
+    'auth/weak-password',
+    'auth/too-many-requests',
+    'auth/network-request-failed',
+    'auth/requires-recent-login',
+    'auth/expired-action-code',
+    'auth/invalid-action-code',
+    'auth/user-token-expired',
+];

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

@@ -0,0 +1,9 @@
+import type { ErrorHandlingParams } from '../types/types';
+/**
+ * Builds a human-readable one-string summary of an `ErrorHandlingParams` —
+ * `[classOrMethodName] Error: <message>` followed by non-empty `Params`/
+ * `IsClient` sections. Never throws (`stringifyUnknown` is safe). Used as
+ * `ErrorHandlingParams.formattedMessage` — read this instead of `error`/
+ * `params` directly when you just want something printable.
+ */
+export default function formatErrorMessage(params: ErrorHandlingParams): string;

package/dist/src/error_handling/format_error_message.js

@@ -0,0 +1,23 @@
+import stringifyUnknown from './stringify_unknown';
+function formatSection(title, value, isClient) {
+    if (value === undefined)
+        return '';
+    const text = stringifyUnknown(value, isClient, true);
+    if (!text || text === '{}' || text === '[]')
+        return '';
+    return `\n${title}: ${text}`;
+}
+/**
+ * Builds a human-readable one-string summary of an `ErrorHandlingParams` —
+ * `[classOrMethodName] Error: <message>` followed by non-empty `Params`/
+ * `IsClient` sections. Never throws (`stringifyUnknown` is safe). Used as
+ * `ErrorHandlingParams.formattedMessage` — read this instead of `error`/
+ * `params` directly when you just want something printable.
+ */
+export default function formatErrorMessage(params) {
+    const { error, classOrMethodName, params: extraParams, isClient } = params;
+    const errorText = stringifyUnknown(error, isClient);
+    const paramsSection = formatSection('Params', extraParams, isClient);
+    const clientSection = isClient ? '\nSource: client' : '';
+    return `[${classOrMethodName}] Error: ${errorText}${paramsSection}${clientSection}`;
+}

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

@@ -0,0 +1,9 @@
+export { default as withErrorHandling } from './with_error_handling';
+export type { WithErrorHandlingOptions } from './with_error_handling';
+export { default as reportError } from './report_error';
+export type { ReportErrorConfig } from './report_error';
+export { default as installConsoleErrorOverride } from './install_console_error_override';
+export { default as stringifyUnknown } from './stringify_unknown';
+export { default as formatErrorMessage } from './format_error_message';
+export { defaultIgnoredConsoleErrors } from './default_ignored_console_errors';
+export type { ErrorHandlingParams, ErrorHandlingRoutingConfig } from '../types/types';

package/dist/src/error_handling/index.js

@@ -0,0 +1,6 @@
+export { default as withErrorHandling } from './with_error_handling';
+export { default as reportError } from './report_error';
+export { default as installConsoleErrorOverride } from './install_console_error_override';
+export { default as stringifyUnknown } from './stringify_unknown';
+export { default as formatErrorMessage } from './format_error_message';
+export { defaultIgnoredConsoleErrors } from './default_ignored_console_errors';

package/dist/src/error_handling/install_console_error_override.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/error_handling/install_console_error_override.bench.js

@@ -0,0 +1,10 @@
+import { bench, describe } from 'vitest';
+import installConsoleErrorOverride from './install_console_error_override';
+describe('installConsoleErrorOverride: repeated install calls (no-op after first)', () => {
+    const originalConsoleError = console.error;
+    console.error = () => { };
+    bench('install() called repeatedly (marker check short-circuits)', () => {
+        installConsoleErrorOverride({ errorHandling: { overrideConsoleError: true } });
+    });
+    console.error = originalConsoleError;
+});

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

@@ -0,0 +1,29 @@
+import { type ReportErrorConfig } from './report_error';
+/**
+ * Replaces the global `console.error` so every `console.error(...)` call is
+ * also routed through `config.errorHandling.onError`/`reportError` — the
+ * original `console.error` still runs afterwards, nothing is swallowed.
+ * Safe to call more than once (a no-op after the first call in this JS
+ * realm — call it separately on the server and on the client, each has its
+ * own `console`). Only takes effect when `config.errorHandling.overrideConsoleError`
+ * is `true`.
+ *
+ * A component stuck in a render-error loop calls `console.error` on every
+ * render — `reportError`'s own dedup/cap (on by default, see
+ * `errorHandling.dedup`/`maxReports`) is what stops that from reporting
+ * unboundedly; this function does not duplicate that cap itself.
+ *
+ * `config.errorHandling.ignoreConsoleErrors` (default
+ * `defaultIgnoredConsoleErrors` — this package's own Firebase Auth error
+ * codes for expected user-input failures) and `ignoreConsoleError` both
+ * skip reporting a matching call while still logging it normally.
+ *
+ * @param config Pass the relevant slices of your `RoutingConfig` directly —
+ *   `{ errorHandling: config.errorHandling, generate: config.generate }`.
+ * @param isClient Passed through to every report's `ErrorHandlingParams.isClient`
+ *   — set `true` when installing from client-side code (e.g. the client
+ *   `LocationzationClientProvider`), omit/`false` on the server. There's no
+ *   `getCloudflareContext`/`ctx.waitUntil` available in the browser, so
+ *   client-side reports always await `onError` directly.
+ */
+export default function installConsoleErrorOverride(config: ReportErrorConfig | undefined, isClient?: boolean): void;

package/dist/src/error_handling/install_console_error_override.js

@@ -0,0 +1,49 @@
+import reportError from './report_error';
+import stringifyUnknown from './stringify_unknown';
+import { defaultIgnoredConsoleErrors } from './default_ignored_console_errors';
+/**
+ * Replaces the global `console.error` so every `console.error(...)` call is
+ * also routed through `config.errorHandling.onError`/`reportError` — the
+ * original `console.error` still runs afterwards, nothing is swallowed.
+ * Safe to call more than once (a no-op after the first call in this JS
+ * realm — call it separately on the server and on the client, each has its
+ * own `console`). Only takes effect when `config.errorHandling.overrideConsoleError`
+ * is `true`.
+ *
+ * A component stuck in a render-error loop calls `console.error` on every
+ * render — `reportError`'s own dedup/cap (on by default, see
+ * `errorHandling.dedup`/`maxReports`) is what stops that from reporting
+ * unboundedly; this function does not duplicate that cap itself.
+ *
+ * `config.errorHandling.ignoreConsoleErrors` (default
+ * `defaultIgnoredConsoleErrors` — this package's own Firebase Auth error
+ * codes for expected user-input failures) and `ignoreConsoleError` both
+ * skip reporting a matching call while still logging it normally.
+ *
+ * @param config Pass the relevant slices of your `RoutingConfig` directly —
+ *   `{ errorHandling: config.errorHandling, generate: config.generate }`.
+ * @param isClient Passed through to every report's `ErrorHandlingParams.isClient`
+ *   — set `true` when installing from client-side code (e.g. the client
+ *   `LocationzationClientProvider`), omit/`false` on the server. There's no
+ *   `getCloudflareContext`/`ctx.waitUntil` available in the browser, so
+ *   client-side reports always await `onError` directly.
+ */
+export default function installConsoleErrorOverride(config, isClient) {
+    if (config?.errorHandling?.overrideConsoleError !== true)
+        return;
+    if (console.error.__isErrorHandlingOverride)
+        return;
+    const originalConsoleError = console.error.bind(console);
+    const override = (message, ...optionalParams) => {
+        originalConsoleError(message, ...optionalParams);
+        const stringified = stringifyUnknown(message, isClient);
+        const ignoreList = config.errorHandling?.ignoreConsoleErrors ?? defaultIgnoredConsoleErrors;
+        if (ignoreList.some((ignored) => stringified.includes(ignored)))
+            return;
+        if (config.errorHandling?.ignoreConsoleError?.(stringified))
+            return;
+        void reportError(config, { error: message, classOrMethodName: 'Global Console Error Handler', params: optionalParams, isClient });
+    };
+    override.__isErrorHandlingOverride = true;
+    console.error = override;
+}

package/dist/src/error_handling/report_error.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/error_handling/report_error.bench.js

@@ -0,0 +1,25 @@
+import { bench, describe } from 'vitest';
+import reportError from './report_error';
+const noopOnError = () => { };
+const waitUntil = () => { };
+const fakeGetCloudflareContext = (() => ({ ctx: { waitUntil } }));
+describe('reportError', () => {
+    bench('default console.error path (no config)', async () => {
+        const original = console.error;
+        console.error = noopOnError;
+        await reportError(undefined, { error: new Error('boom'), classOrMethodName: 'bench' });
+        console.error = original;
+    });
+    bench('custom onError, no getCloudflareContext (awaited inline)', async () => {
+        await reportError({ errorHandling: { onError: noopOnError } }, { error: new Error('boom'), classOrMethodName: 'bench' });
+    });
+    bench('backgrounded via ctx.waitUntil', async () => {
+        await reportError({ errorHandling: { onError: noopOnError }, generate: { getCloudflareContext: fakeGetCloudflareContext } }, { error: new Error('boom'), classOrMethodName: 'bench' });
+    });
+    bench('skipped entirely (enable: false, no formatting cost paid)', async () => {
+        await reportError({ errorHandling: { enable: false, onError: noopOnError } }, { error: new Error('boom'), classOrMethodName: 'bench' });
+    });
+    bench('skipped entirely (consent: false)', async () => {
+        await reportError({ errorHandling: { onError: noopOnError } }, { error: new Error('boom'), classOrMethodName: 'bench', consent: false });
+    });
+});

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

@@ -0,0 +1,34 @@
+import type { ErrorHandlingParams, ErrorHandlingRoutingConfig, GenerateRoutingConfig } from '../types/types';
+export interface ReportErrorConfig {
+    errorHandling?: ErrorHandlingRoutingConfig;
+    generate?: GenerateRoutingConfig;
+}
+/**
+ * Reports `params` via `config.errorHandling.onError` (default
+ * `console.error(params.formattedMessage)`), unless
+ * `config.errorHandling.enable === false`, `params.consent` is set and not
+ * `true` (reporting to a third party without cookie consent can itself be
+ * GDPR-relevant), or dedup throttles it (on by default — see
+ * `errorHandling.dedup`/`throttleMs`/`resetDedup`). Never throws — a broken
+ * reporter must not mask the original error.
+ *
+ * Always overwrites `params.formattedMessage` with a fresh
+ * `formatErrorMessage(params)` before reporting — a human-readable one-line
+ * summary (`[classOrMethodName] Error: <message>` plus non-empty sections)
+ * instead of the raw `error`/`params` object, for a default reporter (or a
+ * simple `onError`) to print directly.
+ *
+ * When `config.generate?.getCloudflareContext` is set, `waitUntil` is called
+ * SYNCHRONOUSLY, in the same tick, with the `callOnError(...)` promise —
+ * Cloudflare Workers only extends the request's lifetime for work already
+ * registered with `waitUntil` by the time the handler returns; deferring
+ * that call through an extra microtask (e.g. `Promise.resolve().then(...)`)
+ * risks the isolate tearing down the request before `waitUntil` is ever
+ * actually invoked, silently dropping the report. Falls back to awaiting
+ * `onError` directly when `getCloudflareContext`/`ctx.waitUntil` is unset or
+ * unavailable (e.g. outside a Cloudflare Worker).
+ *
+ * @param config Pass the relevant slices of your `RoutingConfig` directly —
+ *   `{ errorHandling: config.errorHandling, generate: config.generate }`.
+ */
+export default function reportError(config: ReportErrorConfig | undefined, params: ErrorHandlingParams): Promise<void>;

package/dist/src/error_handling/report_error.js

@@ -0,0 +1,81 @@
+import formatErrorMessage from './format_error_message';
+import stringifyUnknown from './stringify_unknown';
+const DEFAULT_THROTTLE_MS = 5000;
+// Module-scope dedup state — safe by default only because a fresh JS realm
+// (isolate/Worker instance) starts with it cleared. In a long-lived server
+// process reused across many requests, pass `resetDedup: true` on the first
+// `reportError` call of each request/cron tick, or one request's errors can
+// suppress another's.
+let lastDedupKey = null;
+let lastReportedAt = 0;
+function buildDedupKey(params) {
+    return params.dedupKey ?? `${params.classOrMethodName} ${stringifyUnknown(params.error, params.isClient)} ${params.params ? stringifyUnknown(params.params, params.isClient) : ''}`;
+}
+async function callOnError(config, params) {
+    const paramsWithFormattedMessage = { ...params, formattedMessage: formatErrorMessage(params) };
+    try {
+        if (config?.onError) {
+            await config.onError(paramsWithFormattedMessage);
+        }
+        else {
+            console.error(paramsWithFormattedMessage.formattedMessage);
+        }
+    }
+    catch {
+        console.error(paramsWithFormattedMessage.formattedMessage);
+    }
+}
+/**
+ * Reports `params` via `config.errorHandling.onError` (default
+ * `console.error(params.formattedMessage)`), unless
+ * `config.errorHandling.enable === false`, `params.consent` is set and not
+ * `true` (reporting to a third party without cookie consent can itself be
+ * GDPR-relevant), or dedup throttles it (on by default — see
+ * `errorHandling.dedup`/`throttleMs`/`resetDedup`). Never throws — a broken
+ * reporter must not mask the original error.
+ *
+ * Always overwrites `params.formattedMessage` with a fresh
+ * `formatErrorMessage(params)` before reporting — a human-readable one-line
+ * summary (`[classOrMethodName] Error: <message>` plus non-empty sections)
+ * instead of the raw `error`/`params` object, for a default reporter (or a
+ * simple `onError`) to print directly.
+ *
+ * When `config.generate?.getCloudflareContext` is set, `waitUntil` is called
+ * SYNCHRONOUSLY, in the same tick, with the `callOnError(...)` promise —
+ * Cloudflare Workers only extends the request's lifetime for work already
+ * registered with `waitUntil` by the time the handler returns; deferring
+ * that call through an extra microtask (e.g. `Promise.resolve().then(...)`)
+ * risks the isolate tearing down the request before `waitUntil` is ever
+ * actually invoked, silently dropping the report. Falls back to awaiting
+ * `onError` directly when `getCloudflareContext`/`ctx.waitUntil` is unset or
+ * unavailable (e.g. outside a Cloudflare Worker).
+ *
+ * @param config Pass the relevant slices of your `RoutingConfig` directly —
+ *   `{ errorHandling: config.errorHandling, generate: config.generate }`.
+ */
+export default async function reportError(config, params) {
+    const errorHandling = config?.errorHandling;
+    if (errorHandling?.resetDedup) {
+        lastDedupKey = null;
+        lastReportedAt = 0;
+    }
+    if (errorHandling?.enable === false)
+        return;
+    if (params.consent !== undefined && params.consent !== true)
+        return;
+    if (errorHandling?.dedup !== false) {
+        const throttleMs = errorHandling?.throttleMs ?? DEFAULT_THROTTLE_MS;
+        const dedupKey = buildDedupKey(params);
+        const now = Date.now();
+        if (dedupKey === lastDedupKey && now - lastReportedAt < throttleMs)
+            return;
+        lastDedupKey = dedupKey;
+        lastReportedAt = now;
+    }
+    const waitUntil = config?.generate?.getCloudflareContext?.({ async: false })?.ctx?.waitUntil;
+    if (waitUntil) {
+        waitUntil(callOnError(errorHandling, params));
+        return;
+    }
+    await callOnError(errorHandling, params);
+}

package/dist/src/error_handling/stringify_unknown.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/error_handling/stringify_unknown.bench.js

@@ -0,0 +1,29 @@
+import { bench, describe } from 'vitest';
+import stringifyUnknown from './stringify_unknown';
+const error = new Error('boom');
+const plainObject = { a: 1, b: { c: 2, d: [1, 2, 3] } };
+const circular = {};
+circular.self = circular;
+describe('stringifyUnknown', () => {
+    bench('string passthrough', () => {
+        stringifyUnknown('already a string');
+    });
+    bench('Error instance', () => {
+        stringifyUnknown(error);
+    });
+    bench('function-wrapped lazy error (server, resolved)', () => {
+        stringifyUnknown(() => 'lazy boom');
+    });
+    bench('function-wrapped lazy error (client, not resolved)', () => {
+        stringifyUnknown(() => 'lazy boom', true);
+    });
+    bench('plain object, pretty-printed', () => {
+        stringifyUnknown(plainObject);
+    });
+    bench('plain object, nested (compact)', () => {
+        stringifyUnknown(plainObject, false, true);
+    });
+    bench('circular object (falls back to [Unserializable value])', () => {
+        stringifyUnknown(circular, false, true);
+    });
+});

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

@@ -0,0 +1,12 @@
+/**
+ * Safely converts an `unknown` value (typically `ErrorHandlingParams.error`)
+ * into a string, for logging/dedup-keying/display — never throws.
+ *
+ * @param isClient Skips resolving function-wrapped/lazy error values on the
+ *   client (matches `ErrorHandlingParams.isClient`) — running arbitrary
+ *   caught functions client-side isn't safe the way it is on the server.
+ * @param isNested Set when stringifying a value nested inside another
+ *   object/array — falls back to a plain `JSON.stringify` (no pretty-print)
+ *   so a single unserializable nested value can't crash the whole report.
+ */
+export default function stringifyUnknown(value: unknown, isClient?: boolean, isNested?: boolean): string;

package/dist/src/error_handling/stringify_unknown.js

@@ -0,0 +1,42 @@
+const MAX_FUNCTION_RESOLUTION_ATTEMPTS = 5;
+function resolveFunctionError(value) {
+    let result = value;
+    try {
+        for (let i = 0; i < MAX_FUNCTION_RESOLUTION_ATTEMPTS && typeof result === 'function'; i++) {
+            result = result();
+        }
+        return result;
+    }
+    catch (error) {
+        return `Error during function resolution: ${String(error)}`;
+    }
+}
+/**
+ * Safely converts an `unknown` value (typically `ErrorHandlingParams.error`)
+ * into a string, for logging/dedup-keying/display — never throws.
+ *
+ * @param isClient Skips resolving function-wrapped/lazy error values on the
+ *   client (matches `ErrorHandlingParams.isClient`) — running arbitrary
+ *   caught functions client-side isn't safe the way it is on the server.
+ * @param isNested Set when stringifying a value nested inside another
+ *   object/array — falls back to a plain `JSON.stringify` (no pretty-print)
+ *   so a single unserializable nested value can't crash the whole report.
+ */
+export default function stringifyUnknown(value, isClient, isNested = false) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Error)
+        return `${value.name}: ${value.message}\n\n${value.stack ?? ''}`;
+    if (typeof value === 'function') {
+        if (isClient)
+            return '[Function]';
+        const resolved = resolveFunctionError(value);
+        return typeof resolved !== 'function' ? stringifyUnknown(resolved, isClient) : '[Function]';
+    }
+    try {
+        return isNested ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+    }
+    catch {
+        return '[Unserializable value]';
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { ConsentValue } from '../cookie_consent/types';
+import { type ReportErrorConfig } from './report_error';
+export interface WithErrorHandlingOptions {
+    /** Pass the relevant slices of your `RoutingConfig` directly — `{ errorHandling: config.errorHandling, generate: config.generate }`. */
+    config?: ReportErrorConfig;
+    params?: unknown;
+    isClient?: boolean;
+    consent?: ConsentValue;
+}
+/**
+ * Wraps `fn`, reporting (via `options.config`) then rethrowing any error it
+ * throws or rejects with. Never swallows — callers keep their own
+ * catch/fallback behavior, this only adds reporting on top.
+ */
+export default function withErrorHandling<Args extends unknown[], Result>(fn: (...args: Args) => Result | Promise<Result>, classOrMethodName: string, options?: WithErrorHandlingOptions): (...args: Args) => Promise<Result>;

package/dist/src/error_handling/with_error_handling.js

@@ -0,0 +1,18 @@
+import reportError from './report_error';
+/**
+ * Wraps `fn`, reporting (via `options.config`) then rethrowing any error it
+ * throws or rejects with. Never swallows — callers keep their own
+ * catch/fallback behavior, this only adds reporting on top.
+ */
+export default function withErrorHandling(fn, classOrMethodName, options = {}) {
+    const { config, params, isClient, consent } = options;
+    return async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (error) {
+            await reportError(config, { error, classOrMethodName, params, isClient, consent });
+            throw error;
+        }
+    };
+}

package/dist/src/firebase_auth/server/firebase_server.js

@@ -3,6 +3,7 @@ import { cache } from 'react';
 import config from '@intl-config';
 import requireFirebaseAuthConfig from '../require_config';
 import { defaultSessionCookieName } from '../middleware/update_session';
+import reportError from '../../error_handling/report_error';
 let baseApp;
 let firebaseAppModule;
 let firebaseAuthModule;
@@ -51,7 +52,8 @@ export const getAuthenticatedAppForUser = cache(async function getAuthenticatedA
         await auth.authStateReady();
         return { firebaseServerApp, currentUser: auth.currentUser };
     }
-    catch {
+    catch (error) {
+        await reportError(config, { error, classOrMethodName: 'getAuthenticatedAppForUser' });
         return { firebaseServerApp: null, currentUser: null };
     }
 });

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

@@ -5,6 +5,8 @@ import dynamic from "next/dynamic";
 import { localesSet } from "../../config/middleware";
 import config from "../../config/intl_config";
 import resolveRequiresConsent from "../../cookie_consent/gdpr_countries";
+import installConsoleErrorOverride from "../../error_handling/install_console_error_override";
+import reportError from "../../error_handling/report_error";
 const LocationzationClientProvider = dynamic(() => import("../../client/components/client_provider"));
 let authUserServerProviderModule;
 /**
@@ -48,6 +50,7 @@ export default async function LocationzationProvider({ language, messages, child
         setMessageForLocaleCache(language, messages);
     }
     const messagesValue = messages ?? await getMessage(language);
+    installConsoleErrorOverride(config);
     let initialAuthUser = null;
     const autoWireClientProvider = config.firebaseAuth?.autoWireClientProvider !== false;
     if (config.firebaseAuth && autoWireClientProvider) {
@@ -68,13 +71,21 @@ export default async function LocationzationProvider({ language, messages, child
         // `getCloudflareContext` path in dev; fail-safe to `true`
         // (banner shown) same as an unresolved country would.
         requiresConsent = !isDevEnvironment
-            ? await resolveRequiresConsent(config.cookieConsent.getCountryCode, config.cookieConsent.getCloudflareContext, config.cookieConsent.gdprCountries)
+            ? await resolveRequiresConsent(config.cookieConsent.getCountryCode, config.generate?.getCloudflareContext, config.cookieConsent.gdprCountries, config.errorHandling)
             : false;
         const analyticsAllowedInEnv = config.cookieConsent.enableAnalyticsInDevMode === true || !isDevEnvironment;
         if (config.cookieConsent.autoWireAnalytics !== false && analyticsAllowedInEnv) {
-            analyticsConfig = config.cookieConsent.getAnalytics
-                ? await config.cookieConsent.getAnalytics()
-                : config.cookieConsent.analytics;
+            if (config.cookieConsent.getAnalytics) {
+                try {
+                    analyticsConfig = await config.cookieConsent.getAnalytics();
+                }
+                catch (error) {
+                    await reportError(config, { error, classOrMethodName: 'getAnalytics' });
+                }
+            }
+            else {
+                analyticsConfig = config.cookieConsent.analytics;
+            }
         }
     }
     return _jsx(LocationzationClientProvider, { language: language, messages: messagesValue, initialAuthUser: initialAuthUser, skipAuthProvider: !autoWireClientProvider, analyticsConfig: analyticsConfig, requiresConsent: requiresConsent, autoWireDialogs: config.cookieConsent?.autoWireDialogs !== false, dialogProps: config.cookieConsent?.dialogProps, updateDialogProps: config.cookieConsent?.updateDialogProps, children: children });

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

@@ -3,6 +3,7 @@ import type { Languages } from 'next/dist/lib/metadata/types/alternative-urls-ty
 import type { Videos } from 'next/dist/lib/metadata/types/metadata-types';
 import type { CookieConsentDialogProps } from '../cookie_consent/client/components/cookie_consent_dialog';
 import type { PrivacyPolicyUpdateDialogProps } from '../cookie_consent/client/components/privacy_policy_update_dialog';
+import type { ConsentValue } from '../cookie_consent/types';
 /**
  * Custom middleware hook, run by `intlMiddleware` for your own logic
  * (e.g. auth, feature flags, A/B tests) — on top of the library's own
@@ -90,6 +91,137 @@ export interface RoutingConfig<AppLocales extends Locales, AppLocalePrefixMode e
      * error if called without this set.
      */
     cookieConsent?: CookieConsentRoutingConfig;
+    /**
+     * Request-time resolvers shared across submodules. Omit entirely to
+     * leave all of them unset.
+     */
+    generate?: GenerateRoutingConfig;
+    /**
+     * Configures the optional `error_handling` submodule (shared
+     * `withErrorHandling`/`reportError` helpers used internally by this
+     * package and available to your own app code). Omit entirely to keep
+     * the defaults: enabled, reporting via `console.error`.
+     */
+    errorHandling?: ErrorHandlingRoutingConfig;
+}
+export interface GenerateRoutingConfig {
+    /**
+     * Pass `getCloudflareContext` from `@opennextjs/cloudflare` directly
+     * (not a dependency of this package, so bring your own import) — its
+     * exact overloaded signature is accepted as-is; called internally with
+     * `{ async: true }`, so you never need to wrap it yourself. Only
+     * `cf.country` is read from the resolved context by `cookieConsent`.
+     *
+     * Country-based gating (via either `cookieConsent.getCountryCode` or
+     * this getter) decides whether the cookie-consent banner is required at
+     * all: visitors outside `gdprCountries` skip the banner and get
+     * analytics immediately (still gated by `enableAnalyticsInDevMode`).
+     * Omit BOTH to require consent for everyone (fail-safe default — the
+     * visitor's country can't be determined at all without either getter).
+     * Set one of the two getters to scope the banner to GDPR regions only.
+     */
+    getCloudflareContext?: CookieConsentGetCloudflareContext;
+}
+export interface ErrorHandlingParams {
+    /** The caught error, in whatever shape it was thrown/rejected with. */
+    error: unknown;
+    /** Name of the function/method the error was caught in, e.g. `"resolveRequiresConsent"`. */
+    classOrMethodName: string;
+    /** Extra context to include in the report (arguments, request info, etc). */
+    params?: unknown;
+    /** Whether this error originated in a client-side (browser) call. */
+    isClient?: boolean;
+    /**
+     * The visitor's current cookie-consent value (from `useCookieConsent()`
+     * or your own server-side resolution), when known. When passed and not
+     * `true`, `reportError`/`withErrorHandling` skip reporting entirely —
+     * sending error reports to a third party (Telegram, Sentry, etc.)
+     * without consent can itself be GDPR-relevant. Omit when consent isn't
+     * applicable (e.g. `cookieConsent` isn't configured at all).
+     */
+    consent?: ConsentValue;
+    /**
+     * Human-readable one-string summary — `[classOrMethodName] Error:
+     * <message>` plus non-empty `Params`/client-origin sections. Set by
+     * `reportError` before calling `onError`/`console.error`; read this
+     * instead of `error`/`params` directly when you just want something
+     * printable. Ignore when passing `params` to `withErrorHandling`
+     * yourself — it's always overwritten.
+     */
+    formattedMessage?: string;
+    /**
+     * Key used by `config.errorHandling.dedupGate` to dedup this report
+     * against the immediately preceding one. Defaults to
+     * `` `${classOrMethodName} ${stringifyUnknown(error)} ${stringifyUnknown(params ?? '')}` ``
+     * when omitted (built by `reportError` itself) — set this explicitly
+     * only if you want a coarser/different dedup key.
+     */
+    dedupKey?: string;
+}
+export interface ErrorHandlingRoutingConfig {
+    /**
+     * Whether errors caught by this package's `withErrorHandling`/
+     * `reportError` helpers are reported at all. Defaults to `true`. Set
+     * `false` to fully disable reporting (errors are still rethrown by
+     * `withErrorHandling`, just never reported).
+     */
+    enable?: boolean;
+    /**
+     * Called with the caught error whenever one is reported. Defaults to
+     * `console.error`. Use this to wire your own error-tracking/logging
+     * transport (Sentry, Telegram, etc).
+     */
+    onError?: (params: ErrorHandlingParams) => void | Promise<void>;
+    /**
+     * Whether `reportError`/`withErrorHandling` replace the global
+     * `console.error` so every `console.error(...)` call in your app is
+     * also routed through `onError` (the original `console.error` still
+     * runs afterwards — nothing is swallowed). Defaults to `false`; call
+     * `installConsoleErrorOverride()` (or pass this `true` and call
+     * `IntlProvider`/`setIntlConfig`'s setup) to install it. Off by default
+     * since this package is shared across apps and a global override is a
+     * bigger behavior change than a plain function call.
+     */
+    overrideConsoleError?: boolean;
+    /**
+     * Substrings matched against the stringified message of each
+     * `console.error(...)` call (only consulted when `overrideConsoleError`
+     * is `true`) — a match skips reporting it (it's still logged normally).
+     * Defaults to `defaultIgnoredConsoleErrors` (this package's own Firebase
+     * Auth error codes for expected user-input failures — wrong password,
+     * email already in use, etc). Pass your own array to replace the
+     * default entirely; pass `[]` to report everything.
+     */
+    ignoreConsoleErrors?: readonly string[];
+    /**
+     * Called with the stringified message of each `console.error(...)` call
+     * (only consulted when `overrideConsoleError` is `true`), in addition to
+     * `ignoreConsoleErrors` — return `true` to skip reporting it (it's still
+     * logged normally). Use this for custom filtering logic beyond a plain
+     * substring match.
+     */
+    ignoreConsoleError?: (message: string) => boolean;
+    /**
+     * Dedup: `reportError` skips reporting an error whose key (`dedupKey`,
+     * or a built-in key derived from `classOrMethodName`/`error`/`params`
+     * when omitted) matches the immediately preceding reported error's key,
+     * within `throttleMs`. On by default (matches this package's own
+     * internal call sites and `installConsoleErrorOverride`'s console-loop
+     * guard). Set `false` to report every distinct call with no dedup at
+     * all.
+     *
+     * The dedup state lives inside `reportError`'s own module — this is
+     * shared mutable state, safe by default only because a fresh JS realm
+     * (isolate/Worker instance) starts with it cleared; in a long-lived
+     * server process reused across many requests, pass `resetDedup: true`
+     * on the first `reportError` call of each request/cron tick to clear it
+     * (otherwise one request's errors can suppress another's).
+     */
+    dedup?: boolean;
+    /** Throttle window in ms: the same dedup key reported again within this window is skipped. Defaults to `5000`. Only consulted when `dedup` isn't `false`. */
+    throttleMs?: number;
+    /** Clears the dedup last-key/timestamp state before processing this call. Pass `true` on the first `reportError` call of each request/cron tick in a long-lived server process. */
+    resetDedup?: boolean;
 }
 export interface CookieConsentRoutingConfig {
     /**
@@ -145,27 +277,10 @@ export interface CookieConsentRoutingConfig {
      * over `getCloudflareContext` when both are set.
      */
     getCountryCode?: () => string | undefined | Promise<string | undefined>;
-    /**
-     * Pass `getCloudflareContext` from `@opennextjs/cloudflare` directly
-     * (not a dependency of this package, so bring your own import) — its
-     * exact overloaded signature is accepted as-is; called internally with
-     * `{ async: true }`, so you never need to wrap it yourself. Only
-     * `cf.country` is read from the resolved context. Ignored when
-     * `getCountryCode` is also set.
-     *
-     * Country-based gating (via either `getCountryCode` or
-     * `getCloudflareContext`) decides whether the cookie-consent banner is
-     * required at all: visitors outside `gdprCountries` skip the banner and
-     * get analytics immediately (still gated by `enableAnalyticsInDevMode`).
-     * Omit BOTH to require consent for everyone (fail-safe default — the
-     * visitor's country can't be determined at all without either getter).
-     * Set one of the two getters to scope the banner to GDPR regions only.
-     */
-    getCloudflareContext?: CookieConsentGetCloudflareContext;
     /**
      * Country codes (ISO 3166-1 alpha-2) for which the cookie-consent banner
      * is required. Only consulted when `getCountryCode` or
-     * `getCloudflareContext` is set. Defaults to the EU/EEA + UK +
+     * `generate.getCloudflareContext` is set. Defaults to the EU/EEA + UK +
      * Switzerland (GDPR/UK-GDPR/nFADP scope). A visitor whose resolved
      * country isn't in this set is treated as NOT requiring consent; a
      * country that couldn't be resolved still requires it (fail-safe:
@@ -203,16 +318,21 @@ export interface CookieConsentRoutingConfig {
     updateDialogProps?: PrivacyPolicyUpdateDialogProps;
 }
 /**
- * Minimal shape read from your `getCloudflareContext()` return value — only
- * `cf.country` is consulted (read defensively at the call site, since `cf`'s
- * real type — `@opennextjs/cloudflare`'s `CfProperties`, a union of the
- * incoming-request and request-init variants — only has `country` on one
- * branch). `cf` is typed loosely here so the real (generic) function is
- * assignable to `CookieConsentGetCloudflareContext` without a hard
- * dependency on that package.
+ * Minimal shape read from your `getCloudflareContext()` return value.
+ * `cf.country` is consulted by `cookieConsent` (read defensively at the call
+ * site, since `cf`'s real type — `@opennextjs/cloudflare`'s `CfProperties`,
+ * a union of the incoming-request and request-init variants — only has
+ * `country` on one branch); `ctx.waitUntil` is used by `error_handling` to
+ * background error reports instead of awaiting them inline. Typed loosely
+ * here so the real (generic) function is assignable to
+ * `CookieConsentGetCloudflareContext` without a hard dependency on that
+ * package.
  */
 export interface CookieConsentCloudflareContext {
     cf?: Record<string, unknown>;
+    ctx?: {
+        waitUntil?: (promise: Promise<unknown>) => void;
+    };
 }
 /**
  * Matches `@opennextjs/cloudflare`'s `getCloudflareContext` overloaded

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.5.7",
+  "version": "0.6.1",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -139,6 +139,26 @@
     "./cookieConsentAnalytics": {
       "types": "./dist/src/cookie_consent/client/components/cookie_consent_analytics.d.ts",
       "import": "./dist/src/cookie_consent/client/components/cookie_consent_analytics.js"
+    },
+    "./errorHandling": {
+      "types": "./dist/src/error_handling/index.d.ts",
+      "import": "./dist/src/error_handling/index.js"
+    },
+    "./installConsoleErrorOverride": {
+      "types": "./dist/src/error_handling/install_console_error_override.d.ts",
+      "import": "./dist/src/error_handling/install_console_error_override.js"
+    },
+    "./stringifyUnknown": {
+      "types": "./dist/src/error_handling/stringify_unknown.d.ts",
+      "import": "./dist/src/error_handling/stringify_unknown.js"
+    },
+    "./formatErrorMessage": {
+      "types": "./dist/src/error_handling/format_error_message.d.ts",
+      "import": "./dist/src/error_handling/format_error_message.js"
+    },
+    "./defaultIgnoredConsoleErrors": {
+      "types": "./dist/src/error_handling/default_ignored_console_errors.d.ts",
+      "import": "./dist/src/error_handling/default_ignored_console_errors.js"
     }
   },
   "scripts": {