cloudflare-next-intl 0.6.14 → 0.6.16

package/dist/src/server/components/server_provider.d.ts

@@ -13,6 +13,64 @@ import type { TranslationObject } from "../../types/types";
  *   otherwise.
  * @param messages Optional pre-loaded messages for `language`. If omitted,
  *   they're loaded via `getMessage(language)`.
+ * @param staticSafe Marks THIS RENDER of `IntlProvider` as one that's safe
+ *   to serve from static rendering / ISR — i.e. the caller already knows
+ *   the current route never needs a server-resolved auth user (a public
+ *   page: marketing, privacy policy, docs, etc). Concretely, setting this
+ *   to `true` skips the internal `resolveAuthUserAndRedirect()` call.
+ *
+ *   ── Why this call is normally made, and why skipping it is safe ──
+ *   When `firebaseAuth` is configured, `IntlProvider` by default calls
+ *   `resolveAuthUserAndRedirect()`, which:
+ *     1. Reads the session cookie via `cookies()` and verifies it against
+ *        Firebase (server-side, authoritative check for "who is this?").
+ *     2. Reads the current pathname via `headers()` (`x-pathname`, set by
+ *        `intlMiddleware`) to redirect guest → `redirectAuthPath` or
+ *        signed-in → `homePath` on an auth page.
+ *     3. Returns the resolved user so the client `AuthUserProvider` can
+ *        render the correct signed-in/signed-out UI on the FIRST paint,
+ *        with zero flash.
+ *   Both `cookies()` and `headers()` are request-scoped APIs — calling
+ *   either one forces Next.js to render the ENTIRE subtree dynamically on
+ *   every request. No static HTML, no ISR, no caching — for that route
+ *   AND every route nested under this same `IntlProvider` call, whether
+ *   or not that specific route actually needs auth. A page in
+ *   `firebaseAuth.whiteListPaths` (meant to be public) is NOT exempt from
+ *   this cost today: the whitelist check happens only AFTER `cookies()`/
+ *   `headers()` are already read, so it's just as dynamic as a protected
+ *   page.
+ *
+ *   The redirect part of step 2 is redundant on any project using the
+ *   default middleware wiring (`firebaseAuth.middlewareEnabled !== false`,
+ *   the default): `intlMiddleware`'s `update_session` step already
+ *   validates the session JWT (refreshing it via Firebase's token API if
+ *   expired) and performs the exact same guest/auth-page redirects —
+ *   authoritatively, on every request, BEFORE this component ever runs.
+ *   So `staticSafe: true` does not weaken auth enforcement — the
+ *   middleware gate still applies unchanged. The only thing you give up
+ *   is step 3: `initialAuthUser` is not seeded server-side, so the client
+ *   `AuthUserProvider` resolves it itself after mount instead. In
+ *   practice this means a signed-in user MAY see this route's
+ *   logged-out-state UI (e.g. a nav avatar placeholder) for one client
+ *   render before the real user data appears — never wrong/protected
+ *   content, since middleware already gated that; just a delayed value.
+ *
+ *   ── When to use it ──
+ *   Set `staticSafe: true` only on `IntlProvider` calls that wrap routes
+ *   you know are always public and don't render auth-dependent UI above
+ *   the fold (or can tolerate that UI appearing a moment late). Leave the
+ *   default (`false`) for any `IntlProvider` call that also wraps
+ *   protected routes or routes where the auth-state flash would be
+ *   visually jarring (dashboards, account pages, anything showing
+ *   `initialAuthUser`-derived content immediately). If you need
+ *   different behavior for public vs protected routes within the SAME
+ *   app, render `IntlProvider` twice — once per layout/route-group, each
+ *   with its own `staticSafe` value — rather than picking one value for
+ *   the whole app. If `firebaseAuth.middlewareEnabled` is explicitly
+ *   `false` (middleware auth disabled), do NOT set `staticSafe: true` —
+ *   this component becomes the ONLY place performing the auth redirect,
+ *   so skipping it there really does remove the security check, not just
+ *   the flash.
  *
  * @example
  * ```tsx
@@ -28,8 +86,9 @@ import type { TranslationObject } from "../../types/types";
  * }
  * ```
  */
-export default function LocationzationProvider({ language, messages, children }: {
+export default function LocationzationProvider({ language, messages, staticSafe, children }: {
     language: string;
     messages?: TranslationObject;
+    staticSafe?: boolean;
     children: React.ReactNode;
 }): Promise<Component>;

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

@@ -23,6 +23,64 @@ let authUserServerProviderModule;
  *   otherwise.
  * @param messages Optional pre-loaded messages for `language`. If omitted,
  *   they're loaded via `getMessage(language)`.
+ * @param staticSafe Marks THIS RENDER of `IntlProvider` as one that's safe
+ *   to serve from static rendering / ISR — i.e. the caller already knows
+ *   the current route never needs a server-resolved auth user (a public
+ *   page: marketing, privacy policy, docs, etc). Concretely, setting this
+ *   to `true` skips the internal `resolveAuthUserAndRedirect()` call.
+ *
+ *   ── Why this call is normally made, and why skipping it is safe ──
+ *   When `firebaseAuth` is configured, `IntlProvider` by default calls
+ *   `resolveAuthUserAndRedirect()`, which:
+ *     1. Reads the session cookie via `cookies()` and verifies it against
+ *        Firebase (server-side, authoritative check for "who is this?").
+ *     2. Reads the current pathname via `headers()` (`x-pathname`, set by
+ *        `intlMiddleware`) to redirect guest → `redirectAuthPath` or
+ *        signed-in → `homePath` on an auth page.
+ *     3. Returns the resolved user so the client `AuthUserProvider` can
+ *        render the correct signed-in/signed-out UI on the FIRST paint,
+ *        with zero flash.
+ *   Both `cookies()` and `headers()` are request-scoped APIs — calling
+ *   either one forces Next.js to render the ENTIRE subtree dynamically on
+ *   every request. No static HTML, no ISR, no caching — for that route
+ *   AND every route nested under this same `IntlProvider` call, whether
+ *   or not that specific route actually needs auth. A page in
+ *   `firebaseAuth.whiteListPaths` (meant to be public) is NOT exempt from
+ *   this cost today: the whitelist check happens only AFTER `cookies()`/
+ *   `headers()` are already read, so it's just as dynamic as a protected
+ *   page.
+ *
+ *   The redirect part of step 2 is redundant on any project using the
+ *   default middleware wiring (`firebaseAuth.middlewareEnabled !== false`,
+ *   the default): `intlMiddleware`'s `update_session` step already
+ *   validates the session JWT (refreshing it via Firebase's token API if
+ *   expired) and performs the exact same guest/auth-page redirects —
+ *   authoritatively, on every request, BEFORE this component ever runs.
+ *   So `staticSafe: true` does not weaken auth enforcement — the
+ *   middleware gate still applies unchanged. The only thing you give up
+ *   is step 3: `initialAuthUser` is not seeded server-side, so the client
+ *   `AuthUserProvider` resolves it itself after mount instead. In
+ *   practice this means a signed-in user MAY see this route's
+ *   logged-out-state UI (e.g. a nav avatar placeholder) for one client
+ *   render before the real user data appears — never wrong/protected
+ *   content, since middleware already gated that; just a delayed value.
+ *
+ *   ── When to use it ──
+ *   Set `staticSafe: true` only on `IntlProvider` calls that wrap routes
+ *   you know are always public and don't render auth-dependent UI above
+ *   the fold (or can tolerate that UI appearing a moment late). Leave the
+ *   default (`false`) for any `IntlProvider` call that also wraps
+ *   protected routes or routes where the auth-state flash would be
+ *   visually jarring (dashboards, account pages, anything showing
+ *   `initialAuthUser`-derived content immediately). If you need
+ *   different behavior for public vs protected routes within the SAME
+ *   app, render `IntlProvider` twice — once per layout/route-group, each
+ *   with its own `staticSafe` value — rather than picking one value for
+ *   the whole app. If `firebaseAuth.middlewareEnabled` is explicitly
+ *   `false` (middleware auth disabled), do NOT set `staticSafe: true` —
+ *   this component becomes the ONLY place performing the auth redirect,
+ *   so skipping it there really does remove the security check, not just
+ *   the flash.
  *
  * @example
  * ```tsx
@@ -38,7 +96,7 @@ let authUserServerProviderModule;
  * }
  * ```
  */
-export default async function LocationzationProvider({ language, messages, children }) {
+export default async function LocationzationProvider({ language, messages, staticSafe = false, children }) {
     if (!localesSet.has(language)) {
         const { notFound } = await import("next/navigation");
         notFound();
@@ -54,10 +112,25 @@ export default async function LocationzationProvider({ language, messages, child
     let initialAuthUser = null;
     const autoWireClientProvider = config.firebaseAuth?.autoWireClientProvider !== false;
     if (config.firebaseAuth && autoWireClientProvider) {
-        if (!authUserServerProviderModule) {
-            authUserServerProviderModule = await import("../../firebase_auth/server/auth_user_server_provider");
+        // `staticSafe: true` with middleware auth disabled would silently
+        // drop the ONLY auth redirect this app has — not just the flash-
+        // prevention seed. Warn loudly rather than let that combination
+        // slip through unnoticed; still honor the caller's choice, since a
+        // hard throw here would be a worse failure mode than a console
+        // warning for what is, after all, a caller-controlled flag.
+        if (staticSafe && config.firebaseAuth.middlewareEnabled === false) {
+            console.warn('[cloudflare-next-intl] IntlProvider was called with `staticSafe: true` while ' +
+                '`firebaseAuth.middlewareEnabled` is `false`. With middleware auth disabled, ' +
+                'this component is the ONLY place performing the auth redirect — skipping it ' +
+                'here removes that protection entirely, it does not just remove a render flash. ' +
+                'Set `staticSafe: false` (or enable middleware auth) for this route.');
+        }
+        if (!staticSafe) {
+            if (!authUserServerProviderModule) {
+                authUserServerProviderModule = await import("../../firebase_auth/server/auth_user_server_provider");
+            }
+            initialAuthUser = await authUserServerProviderModule.resolveAuthUserAndRedirect();
         }
-        initialAuthUser = await authUserServerProviderModule.resolveAuthUserAndRedirect();
     }
     let analyticsConfig;
     let requiresConsent = true;

package/package.json

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