cloudflare-next-intl 0.4.0 → 0.4.2

package/README.md

@@ -193,11 +193,21 @@ auto-wires `CookieConsentProvider` (and `CookieConsentAnalytics`, if
 
 ```typescript
 // intl-config.ts
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
 export default setIntlConfig({
     locales: ["en", "de"],
     defaultLocale: "en",
     cookieConsent: {
         privacyPolicyDate: "2026-01-01",
+        // 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,
+        // gdprCountries: [...], // defaults to EU/EEA + UK + Switzerland
+        // enableAnalyticsInDevMode: true, // analytics stay off in dev otherwise
     },
 });
 ```

package/dist/src/client/components/client_provider.d.ts

@@ -6,7 +6,7 @@ interface LocaleContextType {
     messages: TranslationObject;
 }
 export declare const LocaleContext: import("react").Context<LocaleContextType | undefined>;
-export default function LocationzationClientProvider({ language, messages, initialAuthUser, skipAuthProvider, analyticsSecrets, children }: {
+export default function LocationzationClientProvider({ language, messages, initialAuthUser, skipAuthProvider, analyticsSecrets, requiresConsent, children }: {
     language: string;
     messages: TranslationObject;
     initialAuthUser?: SerializedAuthUser | null;
@@ -14,6 +14,13 @@ export default function LocationzationClientProvider({ language, messages, initi
     skipAuthProvider?: boolean;
     /** Resolved server-side from `cookieConsent.secrets`/`getSecrets` when `autoWireAnalytics` isn't `false`. */
     analyticsSecrets?: CookieConsentAnalyticsSecrets;
+    /**
+     * Resolved server-side from `cookieConsent.getCountryCode`/`gdprCountries`.
+     * `false` means the visitor's country doesn't require the consent
+     * banner — `CookieConsentProvider` seeds consent as implicitly granted
+     * for a first-time visitor instead of `null`.
+     */
+    requiresConsent?: boolean;
     children: React.ReactNode;
 }): Component;
 export {};

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

@@ -15,7 +15,7 @@ export const LocaleContext = createContext(undefined);
 const AuthUserProvider = dynamic(() => import("../../firebase_auth/client/auth_user_provider"));
 const CookieConsentProvider = dynamic(() => import("../../cookie_consent/client/cookie_consent_provider"));
 const CookieConsentAnalytics = dynamic(() => import("../../cookie_consent/client/components/cookie_consent_analytics"));
-export default function LocationzationClientProvider({ language, messages, initialAuthUser = null, skipAuthProvider = false, analyticsSecrets, children }) {
+export default function LocationzationClientProvider({ language, messages, initialAuthUser = null, skipAuthProvider = false, analyticsSecrets, requiresConsent = true, children }) {
     setLocaleCache(language);
     setMessageForLocaleCache(language, messages);
     // `LocaleContext.Provider` stays the outermost element here — the
@@ -28,7 +28,7 @@ export default function LocationzationClientProvider({ language, messages, initi
         providedChildren = _jsx(AuthUserProvider, { initialUser: initialAuthUser, children: children });
     }
     if (config.cookieConsent) {
-        providedChildren = _jsxs(CookieConsentProvider, { children: [providedChildren, analyticsSecrets && _jsx(CookieConsentAnalytics, { secrets: analyticsSecrets })] });
+        providedChildren = _jsxs(CookieConsentProvider, { requiresConsent: requiresConsent, children: [providedChildren, analyticsSecrets && _jsx(CookieConsentAnalytics, { secrets: analyticsSecrets })] });
     }
     const contextValue = useMemo(() => ({ language, messages }), [language, messages]);
     return _jsx(LocaleContext.Provider, { value: contextValue, children: providedChildren });

package/dist/src/cookie_consent/client/cookie_consent_provider.d.ts

@@ -13,6 +13,14 @@ export declare const CookieConsentContext: import("react").Context<CookieConsent
  * `privacyPolicyUpdated` becomes `true` until they call
  * `acknowledgePrivacyPolicyUpdate()`.
  *
+ * @param requiresConsent Resolved server-side from
+ *   `cookieConsent.getCountryCode`/`gdprCountries` — `false` means the
+ *   visitor's country doesn't require the banner at all, so a first-time
+ *   visitor (no stored cookie) gets `consent` seeded to `true` instead of
+ *   `null`, skipping the dialog and unlocking analytics immediately.
+ *   Defaults to `true` (always show the banner) when omitted, e.g. when
+ *   `cookieConsent.getCountryCode` isn't configured.
+ *
  * @example
  * ```tsx
  * <CookieConsentProvider>
@@ -22,6 +30,7 @@ export declare const CookieConsentContext: import("react").Context<CookieConsent
  * </CookieConsentProvider>
  * ```
  */
-export default function CookieConsentProvider({ children }: {
+export default function CookieConsentProvider({ requiresConsent, children }: {
+    requiresConsent?: boolean;
     children: React.ReactNode;
 }): React.ReactElement;

package/dist/src/cookie_consent/client/cookie_consent_provider.js

@@ -27,6 +27,14 @@ function parseConsent(raw) {
  * `privacyPolicyUpdated` becomes `true` until they call
  * `acknowledgePrivacyPolicyUpdate()`.
  *
+ * @param requiresConsent Resolved server-side from
+ *   `cookieConsent.getCountryCode`/`gdprCountries` — `false` means the
+ *   visitor's country doesn't require the banner at all, so a first-time
+ *   visitor (no stored cookie) gets `consent` seeded to `true` instead of
+ *   `null`, skipping the dialog and unlocking analytics immediately.
+ *   Defaults to `true` (always show the banner) when omitted, e.g. when
+ *   `cookieConsent.getCountryCode` isn't configured.
+ *
  * @example
  * ```tsx
  * <CookieConsentProvider>
@@ -36,7 +44,7 @@ function parseConsent(raw) {
  * </CookieConsentProvider>
  * ```
  */
-export default function CookieConsentProvider({ children }) {
+export default function CookieConsentProvider({ requiresConsent = true, children }) {
     const { consentCookieName, dateCookieName, maxAge, policyDate } = useMemo(() => {
         const cc = requireCookieConsentConfig(config.cookieConsent);
         return {
@@ -51,6 +59,10 @@ export default function CookieConsentProvider({ children }) {
     const [privacyPolicyUpdated, setPrivacyPolicyUpdated] = useState(false);
     useEffect(() => {
         const storedConsent = parseConsent(getCookie(consentCookieName));
+        if (storedConsent === null && !requiresConsent) {
+            setConsentState(true);
+            return;
+        }
         setConsentState(storedConsent);
         if (storedConsent === null || !policyDate)
             return;

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

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

package/dist/src/cookie_consent/gdpr_countries.bench.js

@@ -0,0 +1,37 @@
+import { bench, describe } from 'vitest';
+import resolveRequiresConsent, { defaultGdprCountries } from './gdpr_countries';
+const fakeGetCloudflareContext = ((options) => {
+    const context = { cf: { country: 'DE' } };
+    return options?.async === false ? context : Promise.resolve(context);
+});
+const customList = ['US', 'CA', 'MX'];
+describe('resolveRequiresConsent: default GDPR list lookup', () => {
+    bench('country inside the list (worst case for Array.includes: near the end)', async () => {
+        await resolveRequiresConsent(() => 'CH', undefined, undefined);
+    });
+    bench('country outside the list', async () => {
+        await resolveRequiresConsent(() => 'US', undefined, undefined);
+    });
+});
+describe('resolveRequiresConsent: custom GDPR list lookup (cached Set)', () => {
+    bench('repeated calls with the same list reference', async () => {
+        await resolveRequiresConsent(() => 'US', undefined, customList);
+    });
+});
+describe('resolveRequiresConsent: gating disabled', () => {
+    bench('neither getter set (fast path, no lookup at all)', async () => {
+        await resolveRequiresConsent(undefined, undefined, undefined);
+    });
+});
+describe('resolveRequiresConsent: getCloudflareContext path', () => {
+    bench('resolves cf.country from an async context getter', async () => {
+        await resolveRequiresConsent(undefined, fakeGetCloudflareContext, undefined);
+    });
+});
+// Sanity check the list itself isn't accidentally growing unbounded — a
+// regression here would also regress the Set-build cost on first use.
+describe('defaultGdprCountries', () => {
+    bench('Set construction cost (paid once per process, not per request)', () => {
+        new Set(defaultGdprCountries);
+    });
+});

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

@@ -0,0 +1,18 @@
+import type { CookieConsentGetCloudflareContext } from '../types/types';
+/**
+ * Default `cookieConsent.gdprCountries` — EU/EEA member states (GDPR),
+ * Iceland/Liechtenstein/Norway (EEA), the UK (UK-GDPR), and Switzerland
+ * (nFADP). ISO 3166-1 alpha-2.
+ */
+export declare const defaultGdprCountries: readonly string[];
+/**
+ * Resolves whether the cookie-consent banner is required for a visitor.
+ *
+ * - Neither getter set: country-based gating is off entirely — consent is
+ *   never required (the simplest opt-in-by-default setup).
+ * - Either getter set: fail-safe — a country that couldn't be resolved
+ *   still requires consent; only a resolved country OUTSIDE
+ *   `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>;

package/dist/src/cookie_consent/gdpr_countries.js

@@ -0,0 +1,52 @@
+/**
+ * Default `cookieConsent.gdprCountries` — EU/EEA member states (GDPR),
+ * Iceland/Liechtenstein/Norway (EEA), the UK (UK-GDPR), and Switzerland
+ * (nFADP). ISO 3166-1 alpha-2.
+ */
+export const defaultGdprCountries = [
+    'AT', 'BE', 'BG', 'CY', 'CZ', 'DE', 'DK', 'EE', 'ES', 'FI', 'FR',
+    'GR', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'PL',
+    'PT', 'RO', 'SE', 'SI', 'SK',
+    'IS', 'LI', 'NO',
+    'GB',
+    'CH',
+];
+// `Set.has()` is O(1) vs `Array.includes()`'s O(n) — this runs on every
+// request that has country-based gating enabled, so the lookup cost matters.
+// Mirrors this package's `localesSet` convention in `config/middleware.ts`.
+const defaultGdprCountriesSet = new Set(defaultGdprCountries);
+// Custom `gdprCountries` lists are typically static config passed at
+// `setIntlConfig` call time (module-scope, stable reference) — caching one
+// Set per distinct array reference avoids rebuilding it on every request
+// while still supporting a caller that legitimately swaps the array.
+const customGdprCountriesSetCache = new WeakMap();
+function getGdprCountriesSet(gdprCountries) {
+    if (!gdprCountries)
+        return defaultGdprCountriesSet;
+    let set = customGdprCountriesSetCache.get(gdprCountries);
+    if (!set) {
+        set = new Set(gdprCountries);
+        customGdprCountriesSetCache.set(gdprCountries, set);
+    }
+    return set;
+}
+/**
+ * Resolves whether the cookie-consent banner is required for a visitor.
+ *
+ * - Neither getter set: country-based gating is off entirely — consent is
+ *   never required (the simplest opt-in-by-default setup).
+ * - Either getter set: fail-safe — a country that couldn't be resolved
+ *   still requires consent; only a resolved country OUTSIDE
+ *   `gdprCountries` skips the banner. `getCountryCode` takes precedence
+ *   over `getCloudflareContext` when both are set.
+ */
+export default async function resolveRequiresConsent(getCountryCode, getCloudflareContext, gdprCountries) {
+    if (!getCountryCode && !getCloudflareContext)
+        return false;
+    const countryCode = getCountryCode
+        ? await getCountryCode()
+        : (await getCloudflareContext({ async: true }))?.cf?.country;
+    if (!countryCode)
+        return true;
+    return getGdprCountriesSet(gdprCountries).has(countryCode);
+}

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

@@ -3,5 +3,6 @@ export { default as useCookieConsent } from './client/use_cookie_consent';
 export { default as CookieConsentDialog } from './client/components/cookie_consent_dialog';
 export { default as PrivacyPolicyUpdateDialog } from './client/components/privacy_policy_update_dialog';
 export { default as CookieConsentAnalytics } from './client/components/cookie_consent_analytics';
+export { defaultGdprCountries } from './gdpr_countries';
 export type { CookieConsentContextType, ConsentValue, CookieDialogClassNames, CookieDialogStyles } from './types';
-export type { CookieConsentRoutingConfig, CookieConsentAnalyticsSecrets } from '../types/types';
+export type { CookieConsentRoutingConfig, CookieConsentAnalyticsSecrets, CookieConsentCloudflareContext, CookieConsentGetCloudflareContext, } from '../types/types';

package/dist/src/cookie_consent/index.js

@@ -3,3 +3,4 @@ export { default as useCookieConsent } from './client/use_cookie_consent';
 export { default as CookieConsentDialog } from './client/components/cookie_consent_dialog';
 export { default as PrivacyPolicyUpdateDialog } from './client/components/privacy_policy_update_dialog';
 export { default as CookieConsentAnalytics } from './client/components/cookie_consent_analytics';
+export { defaultGdprCountries } from './gdpr_countries';

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

@@ -4,6 +4,7 @@ import { getMessage } from "../functions/server";
 import dynamic from "next/dynamic";
 import { localesSet } from "../../config/middleware";
 import config from "../../config/intl_config";
+import resolveRequiresConsent from "../../cookie_consent/gdpr_countries";
 const LocationzationClientProvider = dynamic(() => import("../../client/components/client_provider"));
 let authUserServerProviderModule;
 /**
@@ -56,10 +57,16 @@ export default async function LocationzationProvider({ language, messages, child
         initialAuthUser = await authUserServerProviderModule.resolveAuthUserAndRedirect();
     }
     let analyticsSecrets;
-    if (config.cookieConsent && config.cookieConsent.autoWireAnalytics !== false) {
-        analyticsSecrets = config.cookieConsent.getSecrets
-            ? await config.cookieConsent.getSecrets()
-            : config.cookieConsent.secrets;
+    let requiresConsent = true;
+    if (config.cookieConsent) {
+        requiresConsent = await resolveRequiresConsent(config.cookieConsent.getCountryCode, config.cookieConsent.getCloudflareContext, config.cookieConsent.gdprCountries);
+        const isDevEnvironment = process.env.NODE_ENV === 'development';
+        const analyticsAllowedInEnv = config.cookieConsent.enableAnalyticsInDevMode === true || !isDevEnvironment;
+        if (config.cookieConsent.autoWireAnalytics !== false && analyticsAllowedInEnv) {
+            analyticsSecrets = config.cookieConsent.getSecrets
+                ? await config.cookieConsent.getSecrets()
+                : config.cookieConsent.secrets;
+        }
     }
-    return _jsx(LocationzationClientProvider, { language: language, messages: messagesValue, initialAuthUser: initialAuthUser, skipAuthProvider: !autoWireClientProvider, analyticsSecrets: analyticsSecrets, children: children });
+    return _jsx(LocationzationClientProvider, { language: language, messages: messagesValue, initialAuthUser: initialAuthUser, skipAuthProvider: !autoWireClientProvider, analyticsSecrets: analyticsSecrets, requiresConsent: requiresConsent, children: children });
 }

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

@@ -1 +1 @@
-export type { CookieAttributes, LocalePrefixMode, Locales, ReturnType, RoutingConfig, TranslationEntry, TranslationObject, TranslatorReturnType, Alternates, changeFrequency, IntlSitemap, CookieConsentRoutingConfig, CookieConsentAnalyticsSecrets, } from './types';
+export type { CookieAttributes, LocalePrefixMode, Locales, ReturnType, RoutingConfig, TranslationEntry, TranslationObject, TranslatorReturnType, Alternates, changeFrequency, IntlSitemap, CookieConsentRoutingConfig, CookieConsentAnalyticsSecrets, CookieConsentCloudflareContext, CookieConsentGetCloudflareContext, } from './types';

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

@@ -128,6 +128,78 @@ export interface CookieConsentRoutingConfig {
      * `undefined` in the returned object disables that provider's script.
      */
     getSecrets?: () => CookieConsentAnalyticsSecrets | Promise<CookieConsentAnalyticsSecrets>;
+    /**
+     * Resolves the visitor's country code directly (ISO 3166-1 alpha-2,
+     * e.g. `"DE"`) — the simplest option when you already have it from
+     * somewhere (a header, a KV lookup, your own logic). Takes precedence
+     * 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 skip country-based gating entirely — the banner is never
+     * shown and consent is treated as implicitly granted for everyone. This
+     * is the simplest opt-in-by-default setup; set one of the two getters
+     * once you need real GDPR-region gating.
+     */
+    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 +
+     * 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:
+     * unknown defaults to "ask").
+     */
+    gdprCountries?: readonly string[];
+    /**
+     * Whether the auto-wired analytics scripts (see `autoWireAnalytics`)
+     * are allowed to load in your local/dev environment. Defaults to
+     * `false` — analytics stay off during local development regardless of
+     * consent, matching most analytics providers' own recommendation not to
+     * pollute production data with dev traffic. Set `true` to test the
+     * scripts locally.
+     */
+    enableAnalyticsInDevMode?: boolean;
+}
+/**
+ * Minimal shape read from your `getCloudflareContext()` return value — only
+ * `cf.country` is consulted, so any superset (the real `CloudflareContext`
+ * from `@opennextjs/cloudflare`) is accepted as-is without a hard
+ * dependency on that package.
+ */
+export interface CookieConsentCloudflareContext {
+    cf?: {
+        country?: string;
+    };
+}
+/**
+ * Matches `@opennextjs/cloudflare`'s `getCloudflareContext` overloaded
+ * signature exactly, so that function can be passed as
+ * `cookieConsent.getCloudflareContext` directly — this package always
+ * calls it with `{ async: true }` internally (the first overload), which is
+ * why that overload's return type drives `resolveRequiresConsent`'s
+ * awaited result; the sync overload is accepted structurally only so the
+ * real function's type (which has both) is assignable as-is.
+ */
+export interface CookieConsentGetCloudflareContext {
+    (options: {
+        async: true;
+    }): Promise<CookieConsentCloudflareContext | null>;
+    (options?: {
+        async: false;
+    }): CookieConsentCloudflareContext | null;
 }
 export interface CookieConsentAnalyticsSecrets {
     /** Cloudflare Web Analytics beacon token, e.g. `'{"token": "..."}'` (the raw `data-cf-beacon` attribute value). */

package/llms.txt

@@ -41,7 +41,8 @@ other subpath can be used.
 - `./useCookieConsent` — context hook; throws `"useCookieConsent must be used within a CookieConsentProvider"` if called outside one.
 - `./CookieConsentDialog` — default cookie-consent banner; accepts per-slot `classNames`/`styles` or a `render` prop for fully custom markup.
 - `./PrivacyPolicyUpdateDialog` — "privacy policy updated" banner; auto-enabled only when `cookieConsent.privacyPolicyDate` is set.
-- `./cookieConsentAnalytics` — `CookieConsentAnalytics`: gates Cloudflare Web Analytics / Google Ads / Google Analytics / AdSense / Microsoft Clarity behind consent; rendered automatically by `IntlProvider` when `cookieConsent.secrets` or `getSecrets` is set (and `autoWireAnalytics !== false`).
+- `./cookieConsentAnalytics` — `CookieConsentAnalytics`: gates Cloudflare Web Analytics / Google Ads / Google Analytics / AdSense / Microsoft Clarity behind consent; rendered automatically by `IntlProvider` when `cookieConsent.secrets` or `getSecrets` is set (and `autoWireAnalytics !== false`). Never renders in local dev (`NODE_ENV === 'development'`) unless `cookieConsent.enableAnalyticsInDevMode` is `true`.
+- Country-based gating (`cookieConsent.getCountryCode` / `getCloudflareContext` + `gdprCountries`): resolved server-side by `IntlProvider` into a `requiresConsent` boolean passed to `CookieConsentProvider`. Neither getter set → gating off, consent always implicitly granted. `getCountryCode` (direct country resolver) takes precedence over `getCloudflareContext` (reads `cf.country`) when both are set. `getCloudflareContext` accepts `@opennextjs/cloudflare`'s `getCloudflareContext` function directly (its exact overloaded signature — `CookieConsentGetCloudflareContext`), called internally with `{ async: true }`. Unresolved country (or a `null` context) always requires consent (fail-safe). `./cookieConsent` also exports `defaultGdprCountries` (EU/EEA + UK + Switzerland).
 
 ## Conventions
 

package/package.json

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