cloudflare-next-intl 0.8.38 → 0.8.40

package/README.md

@@ -188,6 +188,55 @@ import { getLocale } from "cloudflare-next-intl/server";
 const locale = await getLocale();
 ```
 
+### Geo & Timezone Resolution (Vinext & Cloudflare)
+
+`cloudflare-next-intl` provides built-in country and timezone resolution methods that work seamlessly in Server Components, Server Actions, Route Handlers, and Middleware under Vinext and OpenNext:
+
+```tsx
+import { getCountry, getTimezone } from "cloudflare-next-intl/server";
+// Or: import { getCountry, getTimezone } from "cloudflare-next-intl/geo";
+
+export default async function Page() {
+    const country = await getCountry(); // e.g. "US", "DE", "UA"
+    const timezone = await getTimezone(undefined, "UTC"); // e.g. "America/New_York", "Europe/Kyiv"
+
+    return <p>Visitor Country: {country}, Timezone: {timezone}</p>;
+}
+```
+
+In middleware or custom handlers, you can pass the `request` or `headers` directly:
+
+```typescript
+import { getCountry, getTimezone } from "cloudflare-next-intl/server";
+
+export function customHandler(request: NextRequest) {
+    const country = getCountry(request);
+    const timezone = getTimezone(request, "UTC");
+}
+```
+
+`intlMiddleware` automatically forwards `x-cf-country` and `x-cf-timezone` headers from `request.cf` so they are immediately available downstream via `next/headers`.
+
+### Vinext Runtime Configuration
+
+When deploying under [Vinext](https://github.com/cloudflare/vinext) with `cloudflare:workers`, you can pass your `env` and execution context (`ctx`) directly in `setIntlConfig`:
+
+```typescript
+// src/i18n/intl_config.ts
+import { setIntlConfig } from "cloudflare-next-intl/setIntlConfig";
+import { env } from "cloudflare:workers";
+import { getRequestExecutionContext } from "vinext/shims/request-context";
+
+export default setIntlConfig({
+    locales: ["en", "de"],
+    defaultLocale: "en",
+    generate: {
+        env,
+        ctx: () => getRequestExecutionContext() ?? undefined,
+    },
+});
+```
+
 ```tsx
 // Client Components ("use client")
 import { useLocale } from "cloudflare-next-intl/use";

package/dist/src/config/middleware.js

@@ -130,6 +130,16 @@ export default async function intlMiddleware(request, options) {
         response.headers.set('Content-Language', effectiveLocaleForRequest);
         response.headers.set('x-pathname', pathWithoutLocale);
         response.headers.set('x-search', search);
+        const country = request.cf?.country ?? request.headers.get('cf-ipcountry') ?? request.headers.get('x-cf-country');
+        if (country) {
+            request.headers.set('x-cf-country', country);
+            response.headers.set('x-cf-country', country);
+        }
+        const timezone = request.cf?.timezone ?? request.headers.get('cf-timezone') ?? request.headers.get('x-cf-timezone');
+        if (timezone) {
+            request.headers.set('x-cf-timezone', timezone);
+            response.headers.set('x-cf-timezone', timezone);
+        }
         // Auto-wires the firebase_auth submodule's redirect/session-refresh
         // logic when `firebaseAuth` is configured — dynamic import so this
         // file never pulls in firebase_auth/** (and transitively firebase/*)

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

@@ -5,14 +5,4 @@ import type { CookieConsentGetCloudflareContext, ErrorHandlingRoutingConfig } fr
  * (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: fail-safe — consent is required by default since
- *   the visitor's country can't be determined at all.
- * - 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, errorHandlingConfig?: ErrorHandlingRoutingConfig): Promise<boolean>;

package/dist/src/cookie_consent/gdpr_countries.js

@@ -31,16 +31,6 @@ function getGdprCountriesSet(gdprCountries) {
     }
     return set;
 }
-/**
- * Resolves whether the cookie-consent banner is required for a visitor.
- *
- * - Neither getter set: fail-safe — consent is required by default since
- *   the visitor's country can't be determined at all.
- * - 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, errorHandlingConfig) {
     if (!getCountryCode && !getCloudflareContext)
         return true;

package/dist/src/db/connection.js

@@ -1,6 +1,7 @@
 import reportError from '../error_handling/report_error';
 import requireDbConfig from './require_config';
 import resolveConfigValue from './resolve_config_value';
+import { resolveEnv } from '../server/functions/geo';
 let pgModule;
 /**
  * Loads `pg` lazily, so an app that never touches the Postgres transport never
@@ -11,13 +12,18 @@ function loadPg() {
     pgModule ?? (pgModule = import('pg'));
     return pgModule;
 }
-async function resolveConnectionString(db) {
+async function resolveConnectionString(db, generate) {
     const configured = await resolveConfigValue(db.connectionString);
     if (configured)
         return configured;
+    const env = await resolveEnv(generate);
+    const hyperdriveConn = env?.HYPERDRIVE?.connectionString;
+    if (hyperdriveConn && hyperdriveConn !== 'postgresql://user:pass@localhost:5432/db') {
+        return hyperdriveConn;
+    }
     throw new Error('db: could not resolve a Postgres connection string. Set `db.connectionString` ' +
         'to a connection string, or to a function returning one (e.g. reading a ' +
-        'Hyperdrive binding off `getCloudflareContext().env`).');
+        'Hyperdrive binding off `env` or `getCloudflareContext().env`).');
 }
 /**
  * Runs `queryFn` on a Postgres client scoped to this single call: one
@@ -29,7 +35,7 @@ async function resolveConnectionString(db) {
 export async function withDbClient(config, queryFn) {
     const db = config.db;
     requireDbConfig(db);
-    const connectionString = await resolveConnectionString(db);
+    const connectionString = await resolveConnectionString(db, config.generate);
     const { Client: PgClient } = await loadPg();
     const client = new PgClient({ connectionString });
     let result;
@@ -50,23 +56,26 @@ export async function withDbClient(config, queryFn) {
     }
     finally {
         const endPromise = connected ? client.end() : Promise.resolve();
-        const getContext = config.generate?.getCloudflareContext;
-        if (!getContext || db.disconnectAfterRequest === false) {
-            await endPromise.catch(() => undefined);
-        }
-        else {
-            try {
-                const context = await getContext({ async: true });
-                if (typeof context?.ctx?.waitUntil === 'function') {
-                    context.ctx.waitUntil(endPromise.catch(() => undefined));
+        let ctx;
+        if (db.disconnectAfterRequest !== false) {
+            if (config.generate?.ctx) {
+                ctx = typeof config.generate.ctx === 'function' ? config.generate.ctx() : config.generate.ctx;
+            }
+            else if (config.generate?.getCloudflareContext) {
+                try {
+                    const context = await config.generate.getCloudflareContext({ async: true });
+                    ctx = context?.ctx;
                 }
-                else {
-                    await endPromise.catch(() => undefined);
+                catch {
+                    // Ignore context resolution errors
                 }
             }
-            catch {
-                await endPromise.catch(() => undefined);
-            }
+        }
+        if (ctx && typeof ctx.waitUntil === 'function') {
+            ctx.waitUntil(endPromise.catch(() => undefined));
+        }
+        else {
+            await endPromise.catch(() => undefined);
         }
     }
     return result;
@@ -99,7 +108,7 @@ export async function withSessionLock(fn) {
 export async function connectToPostgres(config) {
     const db = config.db;
     requireDbConfig(db);
-    const connectionString = await resolveConnectionString(db);
+    const connectionString = await resolveConnectionString(db, config.generate);
     const { Client: PgClient } = await loadPg();
     const client = new PgClient({ connectionString });
     client.on('error', (error) => {

package/dist/src/error_handling/report_error.js

@@ -127,11 +127,21 @@ export default async function reportError(config, params) {
         lastDedupKey = dedupKey;
         lastReportedAt = now;
     }
-    // `getCloudflareContext` only exists server-side inside a Cloudflare
-    // Worker (with `initOpenNextCloudflareForDev` set up in dev) — calling
-    // it at all for a client-originated report throws synchronously, before
-    // any "is it available" check can run.
-    const ctx = params.isClient ? undefined : config?.generate?.getCloudflareContext?.({ async: false })?.ctx;
+    let ctx;
+    if (!params.isClient) {
+        const generate = config?.generate;
+        if (generate?.ctx) {
+            ctx = typeof generate.ctx === 'function' ? generate.ctx() : generate.ctx;
+        }
+        else if (generate?.getCloudflareContext) {
+            try {
+                ctx = generate.getCloudflareContext({ async: false })?.ctx;
+            }
+            catch {
+                // Ignore context errors
+            }
+        }
+    }
     if (ctx?.waitUntil) {
         ctx.waitUntil(callOnError(errorHandling, params));
         return;

package/dist/src/server/functions/geo.bench.d.ts

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

package/dist/src/server/functions/geo.bench.js

@@ -0,0 +1,14 @@
+import { bench, describe } from 'vitest';
+import { getCountry, getTimezone } from './geo';
+describe('geo benchmarks', () => {
+    const headers = new Headers({
+        'x-cf-country': 'UA',
+        'x-cf-timezone': 'Europe/Kyiv',
+    });
+    bench('getCountry with Headers', async () => {
+        await getCountry(headers);
+    });
+    bench('getTimezone with Headers', async () => {
+        await getTimezone(headers);
+    });
+});

package/dist/src/server/functions/geo.d.ts

@@ -0,0 +1,25 @@
+import type { GenerateRoutingConfig, RequestOrHeaders } from '../../types/types';
+/**
+ * Resolves the client's ISO 3166-1 alpha-2 country code (e.g. "US", "DE", "UA").
+ *
+ * Checks in order:
+ * 1. Explicit `input` (Request, NextRequest, or Headers) if provided
+ * 2. Next.js request headers via `headers()` (`x-cf-country`, `cf-ipcountry`)
+ * 3. `generate.getCloudflareContext` or `cf.country` if passed
+ * 4. `undefined` if outside request scope or unavailable
+ */
+export declare function getCountry(input?: RequestOrHeaders, generate?: GenerateRoutingConfig): Promise<string | undefined>;
+/**
+ * Resolves the client's IANA timezone string (e.g. "America/New_York", "Europe/Kyiv", "UTC").
+ *
+ * Checks in order:
+ * 1. Explicit `input` (Request, NextRequest, or Headers) if provided
+ * 2. Next.js request headers via `headers()` (`x-cf-timezone`, `cf-timezone`)
+ * 3. `generate.getCloudflareContext` or `cf.timezone` if passed
+ * 4. `fallback` (or `undefined`) if outside request scope or unavailable
+ */
+export declare function getTimezone(input?: RequestOrHeaders, fallback?: string, generate?: GenerateRoutingConfig): Promise<string | undefined>;
+/**
+ * Resolves the Cloudflare environment bindings object from `generate.env` or `generate.getCloudflareContext`.
+ */
+export declare function resolveEnv(generate?: GenerateRoutingConfig): Promise<Record<string, unknown> | undefined>;

package/dist/src/server/functions/geo.js

@@ -0,0 +1,128 @@
+function extractHeader(h, name) {
+    if (typeof h.get === 'function') {
+        const val = h.get(name);
+        return val ?? undefined;
+    }
+    const rec = h;
+    const val = rec[name] ?? rec[name.toLowerCase()];
+    return (typeof val === 'string' && val.length > 0) ? val : undefined;
+}
+/**
+ * Resolves the client's ISO 3166-1 alpha-2 country code (e.g. "US", "DE", "UA").
+ *
+ * Checks in order:
+ * 1. Explicit `input` (Request, NextRequest, or Headers) if provided
+ * 2. Next.js request headers via `headers()` (`x-cf-country`, `cf-ipcountry`)
+ * 3. `generate.getCloudflareContext` or `cf.country` if passed
+ * 4. `undefined` if outside request scope or unavailable
+ */
+export async function getCountry(input, generate) {
+    if (input) {
+        if ('headers' in input && input.headers) {
+            const country = extractHeader(input.headers, 'x-cf-country') ?? extractHeader(input.headers, 'cf-ipcountry');
+            if (country)
+                return country;
+        }
+        else if (typeof input.get === 'function') {
+            const country = input.get('x-cf-country') ?? input.get('cf-ipcountry') ?? undefined;
+            if (country)
+                return country;
+        }
+        const cf = input.cf;
+        if (cf?.country && typeof cf.country === 'string' && cf.country.length > 0) {
+            return cf.country;
+        }
+    }
+    try {
+        const { headers } = await import('next/headers');
+        const h = await headers();
+        const country = h.get('x-cf-country') ?? h.get('cf-ipcountry') ?? undefined;
+        if (country)
+            return country;
+    }
+    catch {
+        // Outside request scope / build time
+    }
+    if (generate?.getCloudflareContext) {
+        try {
+            const ctx = await generate.getCloudflareContext({ async: true });
+            if (ctx?.cf?.country && typeof ctx.cf.country === 'string' && ctx.cf.country.length > 0) {
+                return ctx.cf.country;
+            }
+        }
+        catch {
+            // Ignore context resolution errors
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolves the client's IANA timezone string (e.g. "America/New_York", "Europe/Kyiv", "UTC").
+ *
+ * Checks in order:
+ * 1. Explicit `input` (Request, NextRequest, or Headers) if provided
+ * 2. Next.js request headers via `headers()` (`x-cf-timezone`, `cf-timezone`)
+ * 3. `generate.getCloudflareContext` or `cf.timezone` if passed
+ * 4. `fallback` (or `undefined`) if outside request scope or unavailable
+ */
+export async function getTimezone(input, fallback, generate) {
+    if (input) {
+        if ('headers' in input && input.headers) {
+            const tz = extractHeader(input.headers, 'x-cf-timezone') ?? extractHeader(input.headers, 'cf-timezone');
+            if (tz)
+                return tz;
+        }
+        else if (typeof input.get === 'function') {
+            const tz = input.get('x-cf-timezone') ?? input.get('cf-timezone') ?? undefined;
+            if (tz)
+                return tz;
+        }
+        const cf = input.cf;
+        if (cf?.timezone && typeof cf.timezone === 'string' && cf.timezone.length > 0) {
+            return cf.timezone;
+        }
+    }
+    try {
+        const { headers } = await import('next/headers');
+        const h = await headers();
+        const tz = h.get('x-cf-timezone') ?? h.get('cf-timezone') ?? undefined;
+        if (tz)
+            return tz;
+    }
+    catch {
+        // Outside request scope
+    }
+    if (generate?.getCloudflareContext) {
+        try {
+            const ctx = await generate.getCloudflareContext({ async: true });
+            if (ctx?.cf?.timezone && typeof ctx.cf.timezone === 'string' && ctx.cf.timezone.length > 0) {
+                return ctx.cf.timezone;
+            }
+        }
+        catch {
+            // Ignore context resolution errors
+        }
+    }
+    return fallback;
+}
+/**
+ * Resolves the Cloudflare environment bindings object from `generate.env` or `generate.getCloudflareContext`.
+ */
+export async function resolveEnv(generate) {
+    if (!generate)
+        return undefined;
+    if (generate.env) {
+        const resolved = typeof generate.env === 'function' ? await generate.env() : generate.env;
+        return resolved;
+    }
+    if (generate.getCloudflareContext) {
+        try {
+            const ctx = await generate.getCloudflareContext({ async: true });
+            return ctx?.env;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}

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

@@ -3,3 +3,4 @@ export { default as IntlProvider } from './components/server_provider';
 export { default as Link } from './components/link';
 export { default as IntlHelperScript } from './components/helper_script';
 export { getLocaleStaticParams } from './functions/locale_static_params';
+export { getCountry, getTimezone, resolveEnv } from './functions/geo';

package/dist/src/server/index.js

@@ -7,3 +7,4 @@ export { default as IntlProvider } from './components/server_provider';
 export { default as Link } from './components/link';
 export { default as IntlHelperScript } from './components/helper_script';
 export { getLocaleStaticParams } from './functions/locale_static_params';
+export { getCountry, getTimezone, resolveEnv } from './functions/geo';

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

@@ -114,6 +114,20 @@ export interface RoutingConfig<AppLocales extends Locales, AppLocalePrefixMode e
     errorHandling?: ErrorHandlingRoutingConfig;
 }
 export interface GenerateRoutingConfig {
+    /**
+     * Cloudflare environment bindings (or getter returning bindings).
+     * Supported in Vinext, Cloudflare Workers, and OpenNext.
+     */
+    env?: object | Record<string, unknown> | (() => object | Record<string, unknown> | Promise<object | Record<string, unknown>>);
+    /**
+     * Request execution context (providing `waitUntil`), or a getter returning it.
+     * In Vinext, `getRequestExecutionContext()` from `vinext/shims/request-context` can be passed.
+     */
+    ctx?: {
+        waitUntil?: (promise: Promise<unknown>) => void;
+    } | (() => {
+        waitUntil?: (promise: Promise<unknown>) => void;
+    } | undefined);
     /**
      * Pass `getCloudflareContext` from `@opennextjs/cloudflare` directly
      * (not a dependency of this package, so bring your own import) — its
@@ -131,6 +145,18 @@ export interface GenerateRoutingConfig {
      */
     getCloudflareContext?: CookieConsentGetCloudflareContext;
 }
+/**
+ * Flexible input accepted by `getCountry()` and `getTimezone()`:
+ * A `Request`, `NextRequest`, `Headers` instance, or an object containing `headers` and/or `cf`.
+ */
+export type RequestOrHeaders = Request | Headers | {
+    headers?: Headers | Record<string, string | null | undefined>;
+    cf?: {
+        country?: string;
+        timezone?: string;
+        [key: string]: unknown;
+    };
+} | undefined;
 export interface ErrorHandlingParams {
     /** The caught error, in whatever shape it was thrown/rejected with. */
     error: unknown;

package/llms.txt

@@ -10,8 +10,9 @@ other subpath can be used.
 
 - `.` — everything, re-exported (prefer the flat subpaths below for smaller bundles).
 - `./client` — client-side barrel: `LocaleLink`, `usePathname`, `setCookieClient`, `getCookieClient`.
-- `./server` — server-side barrel: `getMessage`, `getTranslations`, `getLocale`, `IntlProvider`, `Link`, `IntlHelperScript`, `getLocaleStaticParams`.
-- `./middleware` — `intlMiddleware` for `middleware.ts`; locale detection/rewrite/redirect.
+- `./server` — server-side barrel: `getMessage`, `getTranslations`, `getLocale`, `getCountry`, `getTimezone`, `resolveEnv`, `IntlProvider`, `Link`, `IntlHelperScript`, `getLocaleStaticParams`.
+- `./geo` / `./getCountry` / `./getTimezone` — country & timezone resolver helpers (`getCountry(input?)`, `getTimezone(input?, fallback?)`, `resolveEnv(generate?)`) for Vinext, OpenNext, and Cloudflare Workers.
+- `./middleware` — `intlMiddleware` for `middleware.ts`; locale detection/rewrite/redirect and automatic CF header forwarding.
 - `./setIntlConfig` — identity function for typed `RoutingConfig` authoring; use in your `@intl-config` file.
 - `./serverProvider` — `IntlProvider` server component (also under `./server`).
 - `./Link` — server-side locale-aware `<Link>` (also under `./server`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.8.38",
+  "version": "0.8.40",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,6 +30,18 @@
       "types": "./dist/src/server/index.d.ts",
       "import": "./dist/src/server/index.js"
     },
+    "./geo": {
+      "types": "./dist/src/server/functions/geo.d.ts",
+      "import": "./dist/src/server/functions/geo.js"
+    },
+    "./getCountry": {
+      "types": "./dist/src/server/functions/geo.d.ts",
+      "import": "./dist/src/server/functions/geo.js"
+    },
+    "./getTimezone": {
+      "types": "./dist/src/server/functions/geo.d.ts",
+      "import": "./dist/src/server/functions/geo.js"
+    },
     "./middleware": {
       "types": "./dist/src/config/middleware.d.ts",
       "import": "./dist/src/config/middleware.js"