npm - @c15t/nextjs - Versions diffs - 2.0.0-rc.0 → 2.0.0-rc.10 - Mend

@c15t/nextjs 2.0.0-rc.0 → 2.0.0-rc.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/README.md +10 -3
package/client/components/consent-dialog-link.js +3 -0
package/dist/headless.cjs +1 -1
package/dist/iab/styles.css +12 -0
package/dist/iab/styles.tw3.css +14 -0
package/dist/index.cjs +1 -1
package/dist/index.js +1 -1
package/dist/libs/browser-initial-data.cjs +1 -0
package/dist/libs/browser-initial-data.js +1 -0
package/dist/libs/initial-data.cjs +1 -1
package/dist/libs/initial-data.js +1 -1
package/dist/styles.css +10 -0
package/dist/styles.tw3.css +13 -0
package/dist/types.cjs +1 -1
package/dist/version.cjs +1 -1
package/dist/version.js +1 -1
package/{dist → dist-types}/headless.d.ts +0 -1
package/{dist → dist-types}/index.d.ts +3 -2
package/dist-types/libs/browser-initial-data.d.ts +9 -0
package/{dist → dist-types}/libs/initial-data.d.ts +7 -2
package/dist-types/types.d.ts +38 -0
package/dist-types/version.d.ts +1 -0
package/docs/README.md +73 -0
package/docs/building-headless-components.md +377 -0
package/docs/callbacks.md +184 -0
package/docs/components/consent-banner.md +269 -0
package/docs/components/consent-dialog-link.md +59 -0
package/docs/components/consent-dialog-trigger.md +103 -0
package/docs/components/consent-dialog.md +177 -0
package/docs/components/consent-manager-provider.md +425 -0
package/docs/components/consent-widget.md +133 -0
package/docs/components/dev-tools.md +63 -0
package/docs/components/frame.md +73 -0
package/docs/concepts/client-modes.md +175 -0
package/docs/concepts/consent-categories.md +97 -0
package/docs/concepts/consent-models.md +116 -0
package/docs/concepts/cookie-management.md +122 -0
package/docs/concepts/glossary.md +23 -0
package/docs/concepts/initialization-flow.md +148 -0
package/docs/concepts/policy-packs.md +229 -0
package/docs/headless.md +190 -0
package/docs/hooks/use-color-scheme.md +40 -0
package/docs/hooks/use-consent-manager/checking-consent.md +94 -0
package/docs/hooks/use-consent-manager/location-info.md +95 -0
package/docs/hooks/use-consent-manager/overview.md +420 -0
package/docs/hooks/use-consent-manager/setting-consent.md +92 -0
package/docs/hooks/use-draggable.md +57 -0
package/docs/hooks/use-focus-trap.md +41 -0
package/docs/hooks/use-reduced-motion.md +35 -0
package/docs/hooks/use-ssr-status.md +31 -0
package/docs/hooks/use-text-direction.md +49 -0
package/docs/hooks/use-translations.md +118 -0
package/docs/iab/consent-banner.md +94 -0
package/docs/iab/consent-dialog.md +134 -0
package/docs/iab/overview.md +126 -0
package/docs/iab/use-gvl-data.md +20 -0
package/docs/iframe-blocking.md +107 -0
package/docs/integrations/building-integrations.md +405 -0
package/docs/integrations/databuddy.md +203 -0
package/docs/integrations/google-tag-manager.md +153 -0
package/docs/integrations/google-tag.md +122 -0
package/docs/integrations/linkedin-insights.md +109 -0
package/docs/integrations/meta-pixel.md +342 -0
package/docs/integrations/microsoft-uet.md +112 -0
package/docs/integrations/overview.md +105 -0
package/docs/integrations/posthog.md +199 -0
package/docs/integrations/tiktok-pixel.md +113 -0
package/docs/integrations/x-pixel.md +143 -0
package/docs/internationalization.md +197 -0
package/docs/network-blocker.md +178 -0
package/docs/optimization.md +234 -0
package/docs/policy-packs.md +246 -0
package/docs/quickstart.md +161 -0
package/docs/script-loader.md +321 -0
package/docs/server-side.md +176 -0
package/docs/styling/classnames.md +92 -0
package/docs/styling/color-scheme.md +82 -0
package/docs/styling/css-variables.md +92 -0
package/docs/styling/overview.md +456 -0
package/docs/styling/slots.md +127 -0
package/docs/styling/tailwind.md +113 -0
package/docs/styling/tokens.md +216 -0
package/docs/troubleshooting.md +146 -0
package/iab/styles.css +1 -0
package/package.json +38 -17
package/readme.json +4 -0
package/src/iab/styles.css +12 -0
package/src/iab/styles.tw3.css +14 -0
package/src/styles.css +10 -0
package/src/styles.tw3.css +13 -0
package/styles.css +1 -0
package/dist/headless.d.ts.map +0 -1
package/dist/index.d.ts.map +0 -1
package/dist/libs/initial-data.d.ts.map +0 -1
package/dist/types.d.ts +0 -16
package/dist/types.d.ts.map +0 -1
package/dist/version.d.ts +0 -2
package/dist/version.d.ts.map +0 -1

package/docs/quickstart.md ADDED Viewed

@@ -0,0 +1,161 @@
+---
+title: Quickstart
+description: Add consent management to your Next.js app in under 5 minutes.
+lastModified: 2026-03-11
+availableIn:
+  - framework: 'javascript'
+    url: '/docs/frameworks/javascript/quickstart'
+    title: 'JavaScript'
+  - framework: 'react'
+    url: '/docs/frameworks/react/quickstart'
+    title: 'React'
+  - framework: 'next'
+    url: '/docs/frameworks/next/quickstart'
+    title: 'Next.js'
+---
+## Via CLI
+|Package manager|Command|
+|:--|:--|
+|npm|`npx @c15t/cli@rc`|
+|pnpm|`pnpm dlx @c15t/cli@rc`|
+|yarn|`yarn dlx @c15t/cli@rc`|
+|bun|`bunx @c15t/cli@rc`|
+## Manual Installation
+1. **Install package**
+   |Package manager|Command|
+   |:--|:--|
+   |npm|`npm install @c15t/nextjs`|
+   |pnpm|`pnpm add @c15t/nextjs`|
+   |yarn|`yarn add @c15t/nextjs`|
+   |bun|`bun add @c15t/nextjs`|
+2. **Import styles** Import the prebuilt component stylesheet in your app-level CSS entrypoint. This is required for styled components to render correctly.
+   ```css
+   @import "@c15t/nextjs/styles.css";
+   ```
+   Keeping the c15t stylesheet in your global CSS entrypoint makes layer and cascade order explicit. JS/TSX side-effect imports can load in a different order across framework and Tailwind tooling, which makes style regressions harder to debug.
+   > ℹ️ Info:
+   >
+   > If you are using the headless API or fully custom styling, you can skip this import. Your root layout should continue importing ./globals.css as usual.
+3. **Create ConsentManager components** Create a provider component with the consent UI and a wrapper that re-exports it. This initializes the consent store and makes consent state available to all child components.
+   ```tsx
+   'use client';
+   import { type ReactNode } from 'react';
+   import {
+     ConsentManagerProvider,
+     ConsentBanner,
+     ConsentDialog,
+   } from '@c15t/nextjs';
+   export default function ConsentManagerClient({ children }: { children: ReactNode }) {
+     return (
+       <ConsentManagerProvider
+         options={{
+           mode: 'hosted',
+           backendURL: 'https://your-instance.c15t.dev',
+           consentCategories: ['necessary', 'measurement', 'marketing'],
+           // Shows banner during development. Remove for production.
+           overrides: { country: 'DE' },
+         }}
+       >
+         <ConsentBanner />
+         <ConsentDialog />
+         {children}
+       </ConsentManagerProvider>
+     );
+   }
+   ```
+   ```tsx
+   import type { ReactNode } from 'react';
+   import ConsentManagerProvider from './provider';
+   export function ConsentManager({ children }: { children: ReactNode }) {
+     return <ConsentManagerProvider>{children}</ConsentManagerProvider>;
+   }
+   ```
+   > ℹ️ Info:
+   >
+   > Hosted mode is the recommended production setup because the backend resolves jurisdiction and policy, keeps durable consent records, and lets c15t recover from temporary network failures by re-syncing later.
+   >
+   > ℹ️ Info:
+   >
+   > Don't have a backend yet? You can use mode: 'offline' for local-only consent storage, but it gives up backend audit history, server-side consent awareness, and automatic jurisdiction detection. Review the browser-only storage consequences before choosing it for production.
+4. **Mount ConsentManager at the app root** Wrap your app tree with ConsentManager so all routes/components can access consent state.
+   ```tsx
+   import { ConsentManager } from '@/components/consent-manager';
+   export default function RootLayout({ children }: { children: React.ReactNode }) {
+     return (
+       <html lang="en">
+         <body>
+           <ConsentManager>{children}</ConsentManager>
+         </body>
+       </html>
+     );
+   }
+   ```
+5. **Verify it works** Start your development server and confirm:
+   A consent banner appears at the bottom of the pageClicking "Customize" opens a dialog with toggles for each consent categoryAfter accepting or rejecting, the banner dismisses and your choice persists across page reloads
+> ℹ️ **Info:**
+> Want better performance and static-route support? See Optimization for rewrites, prefetching, and network tuning. If you want server-side data prefetching, see Server-Side Data Fetching.
+## Optional: Add DevTools
+Install DevTools only if you want a runtime inspector while building and debugging:
+|Package manager|Command|
+|:--|:--|
+|npm|`npm install @c15t/dev-tools`|
+|pnpm|`pnpm add @c15t/dev-tools`|
+|yarn|`yarn add @c15t/dev-tools`|
+|bun|`bun add @c15t/dev-tools`|
+Then add it inside your existing provider:
+```tsx title="components/consent-manager/provider.tsx"
+import { DevTools } from '@c15t/dev-tools/react';
+// ...
+<ConsentManagerProvider options={...}>
+  <ConsentBanner />
+  <ConsentDialog />
+  {process.env.NODE_ENV !== 'production' && <DevTools />}
+  {children}
+</ConsentManagerProvider>
+```
+> ℹ️ **Info:**
+> Want to understand what's happening under the hood? See Initialization Flow for the lifecycle and Cookie Management for script/cookie behavior and revocation handling.
+## Optional: AI Agents
+Install c15t agent skills to let AI agents help with styling, i18n, scripts & other configuration.
+|Package manager|Command|
+|:--|:--|
+|npm|`npx @c15t/cli@rc skills`|
+|pnpm|`pnpm dlx @c15t/cli@rc skills`|
+|yarn|`yarn dlx @c15t/cli@rc skills`|
+|bun|`bunx @c15t/cli@rc skills`|
+See [AI Agents](/docs/ai-agents) for bundled package docs and agent skills.
+## Next steps

package/docs/script-loader.md ADDED Viewed

@@ -0,0 +1,321 @@
+---
+title: Script Loader
+description: Gate third-party scripts behind consent - load Google Analytics, Meta Pixel, and other tracking scripts only when users grant permission.
+---
+The script loader manages third-party scripts based on consent state. Scripts are defined in the provider's `scripts` option and are automatically loaded when their required consent category is granted, and unloaded when consent is revoked.
+c15t has a collection of premade scripts available in `@c15t/scripts`. Check the [integrations overview](/docs/integrations/overview) first before manually building a script.
+|Package manager|Command|
+|:--|:--|
+|npm|`npm install @c15t/scripts`|
+|pnpm|`pnpm add @c15t/scripts`|
+|yarn|`yarn add @c15t/scripts`|
+|bun|`bun add @c15t/scripts`|
+> ℹ️ **Info:**
+> We recommend using the pre-built integrations when possible.
+>
+> ℹ️ **Info:**
+> If you need a vendor we do not ship yet, see the custom integration guide. It covers both one-off Script objects and reusable manifest-backed integrations.
+>
+> ℹ️ **Info:**
+> For app-specific scripts, use a plain Script object. For reusable integrations, prefer a manifest-backed helper so startup phases, consent signaling, and future server-side loading support stay structured.
+## Basic Usage
+Pass an array of `Script` objects to the provider:
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { metaPixel } from '@c15t/scripts/meta-pixel';
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts: [
+          metaPixel({ pixelId: '123456' }),
+          {
+            id: 'custom-analytics',
+            src: 'https://cdn.example.com/analytics.js',
+            category: 'measurement',
+          },
+        ],
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+## Choose the Right Approach
+* Use a plain `Script` for one-off app code.
+* Use a manifest-backed helper in `@c15t/scripts` for reusable integrations, contributions, or anything that needs structured startup behavior.
+If you are building something reusable, start with the [custom integration guide](/docs/integrations/building-integrations) before using raw callbacks.
+## Reusable Integrations
+For app-specific use, raw `Script` objects are usually enough.
+For reusable integrations, c15t uses a manifest-backed model in `@c15t/scripts`. That keeps startup phases, consent signaling, and vendor-specific boot logic structured instead of hidden inside large callback bodies.
+If you are building an integration for multiple apps or contributing upstream, use the [custom integration guide](/docs/integrations/building-integrations).
+## Script Types
+### Standard Scripts
+Load an external JavaScript file via a `<script>` tag. Use `src` to specify the URL.
+### Inline Scripts
+Execute inline JavaScript code. Use `textContent` instead of `src`:
+```tsx
+{
+  id: 'gtag-config',
+  textContent: `
+    window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+    gtag('config', 'G-XXXXXX');
+  `,
+  category: 'measurement',
+}
+```
+### Callback-Only Scripts
+Don't inject any `<script>` tag - just execute callbacks based on consent changes. Useful for controlling libraries that are already loaded:
+```tsx
+{
+  id: 'posthog-consent',
+  callbackOnly: true,
+  category: 'measurement',
+  onLoad: ({ hasConsent }) => {
+    if (hasConsent) {
+      posthog.opt_in_capturing();
+    }
+  },
+  onConsentChange: ({ hasConsent }) => {
+    if (hasConsent) {
+      posthog.opt_in_capturing();
+    } else {
+      posthog.opt_out_capturing();
+    }
+  },
+}
+```
+## Consent Conditions
+The `category` field accepts a `HasCondition` - either a simple string or a logical expression:
+```tsx
+// Simple: requires measurement consent
+{ category: 'measurement' }
+// AND: requires both measurement and marketing
+{ category: { and: ['measurement', 'marketing'] } }
+// OR: requires either measurement or marketing
+{ category: { or: ['measurement', 'marketing'] } }
+```
+## Script Callbacks
+Every script supports four lifecycle callbacks:
+|Callback|When|Use Case|
+|--|--|--|
+|`onBeforeLoad`|Before the script tag is injected|Set up global variables|
+|`onLoad`|Script loaded successfully|Initialize the library|
+|`onError`|Script failed to load|Log error, load fallback|
+|`onConsentChange`|Consent state changed (script already loaded)|Toggle tracking on/off|
+```tsx
+{
+  id: 'analytics',
+  src: 'https://analytics.example.com/v2.js',
+  category: 'measurement',
+  onBeforeLoad: ({ id }) => {
+    console.log(`Loading script: ${id}`);
+  },
+  onLoad: ({ element }) => {
+    window.analytics.init('my-key');
+  },
+  onError: ({ error }) => {
+    console.error('Failed to load analytics:', error);
+  },
+  onConsentChange: ({ hasConsent, consents }) => {
+    window.analytics.setConsent(hasConsent);
+  },
+}
+```
+## Advanced Options
+### Always Load
+Scripts that manage their own consent internally (like GTM in consent mode):
+```tsx
+{
+  id: 'google-tag-manager',
+  src: 'https://www.googletagmanager.com/gtm.js?id=GTM-XXXX',
+  category: 'measurement',
+  alwaysLoad: true, // Loads regardless of consent state
+}
+```
+### Persist After Revocation
+Keep the script loaded even after consent is revoked (the page won't reload for this script):
+```tsx
+{
+  id: 'error-tracking',
+  src: 'https://errors.example.com/track.js',
+  category: 'measurement',
+  persistAfterConsentRevoked: true,
+}
+```
+### Script Placement
+Control where in the DOM the script is injected:
+```tsx
+{
+  id: 'widget',
+  src: 'https://widget.example.com/embed.js',
+  category: 'experience',
+  target: 'body', // 'head' (default) or 'body'
+}
+```
+### Ad Blocker Evasion
+Script element IDs are anonymized by default to avoid ad blocker pattern matching:
+```tsx
+{
+  id: 'analytics',
+  src: '...',
+  category: 'measurement',
+  anonymizeId: true, // default: true
+}
+```
+## Dynamic Script Management
+Add, remove, or check scripts at runtime via `useConsentManager()`:
+```tsx
+import { useConsentManager } from '@c15t/nextjs';
+function ScriptManager() {
+  const { setScripts, removeScript, isScriptLoaded, getLoadedScriptIds } = useConsentManager();
+  // Add scripts dynamically
+  setScripts([{ id: 'dynamic', src: '...', category: 'measurement' }]);
+  // Remove a script
+  removeScript('dynamic');
+  // Check if a script is loaded
+  const loaded = isScriptLoaded('google-analytics');
+  // Get all loaded script IDs
+  const allLoaded = getLoadedScriptIds();
+}
+```
+## API Reference
+### Script
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|Unique identifier for the script|-|✅ Required|
+|src|string \|undefined|URL of the script to load|-|Optional|
+|textContent|string \|undefined|Inline JavaScript code to execute|-|Optional|
+|category|HasCondition\<AllConsentNames>|Consent category or condition required to load this script|-|✅ Required|
+|callbackOnly|boolean \|undefined|Whether this is a callback-only script that doesn't need to load an external resource. When true, no script tag will be added to the DOM, only callbacks will be executed.|false|Optional|
+|persistAfterConsentRevoked|boolean \|undefined|Whether the script should persist after consent is revoked.|false|Optional|
+|alwaysLoad|boolean \|undefined|Whether the script should always load regardless of consent state. This is useful for scripts like Google Tag Manager or PostHog that manage their own consent state internally. The script will load immediately and never be unloaded based on consent changes. Note: When using this option, you are responsible for ensuring the script itself respects user consent preferences through its own consent management.|false|Optional|
+|fetchPriority|"high" \|"low" \|"auto" \|undefined|Priority hint for browser resource loading|-|Optional|
+|attributes|Record\<string, string> \|undefined|Additional attributes to add to the script element|-|Optional|
+|async|boolean \|undefined|Whether to use async loading|-|Optional|
+|defer|boolean \|undefined|Whether to defer script loading|-|Optional|
+|nonce|string \|undefined|Content Security Policy nonce|-|Optional|
+|anonymizeId|boolean \|undefined|Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockers|true|Optional|
+|target|"head" \|"body" \|undefined|Where to inject the script element in the DOM. Options: \`'head'\`: Scripts are appended to \`\<head>\` (default); \`'body'\`: Scripts are appended to \`\<body>\`|'head'|Optional|
+|onBeforeLoad|Object \|undefined|Callback executed before the script is loaded|-|Optional|
+|onLoad|Object \|undefined|Callback executed when the script loads successfully|-|Optional|
+|onError|Object \|undefined|Callback executed if the script fails to load|-|Optional|
+|onConsentChange|Object \|undefined|Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.|-|Optional|
+|vendorId|string \|number \|undefined|IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over \`category\` when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.|-|Optional|
+|iabPurposes|number\[] \|undefined|IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.|-|Optional|
+|iabLegIntPurposes|number\[] \|undefined|IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.|-|Optional|
+|iabSpecialFeatures|number\[] \|undefined|IAB TCF special feature IDs this script requires. Options: 1: Use precise geolocation data; 2: Actively scan device characteristics for identification|-|Optional|
+#### `onBeforeLoad`
+Callback executed before the script is loaded
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|The original script ID|-|✅ Required|
+|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
+|hasConsent|boolean|Has consent|-|✅ Required|
+|consents|ConsentState|The current consent state|-|✅ Required|
+|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
+|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
+#### `onLoad`
+Callback executed when the script loads successfully
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|The original script ID|-|✅ Required|
+|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
+|hasConsent|boolean|Has consent|-|✅ Required|
+|consents|ConsentState|The current consent state|-|✅ Required|
+|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
+|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
+#### `onError`
+Callback executed if the script fails to load
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|The original script ID|-|✅ Required|
+|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
+|hasConsent|boolean|Has consent|-|✅ Required|
+|consents|ConsentState|The current consent state|-|✅ Required|
+|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
+|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
+#### `onConsentChange`
+Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|The original script ID|-|✅ Required|
+|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
+|hasConsent|boolean|Has consent|-|✅ Required|
+|consents|ConsentState|The current consent state|-|✅ Required|
+|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
+|error|Error \|undefined|Error information (for error callbacks)|-|Optional|

package/docs/server-side.md ADDED Viewed

@@ -0,0 +1,176 @@
+---
+title: Server-Side Data Fetching
+description: Pre-fetch consent data in Server Components with fetchInitialData for dynamic Next.js routes.
+---
+The `@c15t/nextjs` package provides `fetchInitialData`, a server-side function that fetches consent data before rendering. Use it when the route is already dynamic, or when you want the fastest first banner and are okay opting the route into dynamic rendering. If you need to keep a route fully static, use `C15tPrefetch` instead.
+Because `fetchInitialData()` resolves request headers from `next/headers`, using it opts the route into dynamic rendering.
+> ℹ️ **Info:**
+> SSR hydration is part of the initialization flow. When SSR data is available, the client skips the API fetch entirely.
+```ts
+import { fetchInitialData } from '@c15t/nextjs';
+```
+## fetchInitialData
+The primary function for fetching consent data on the server. It calls the c15t backend's `/init` endpoint with the user's request headers (resolved automatically from `next/headers`) and returns the initial consent data.
+```ts title="app/layout.tsx"
+import { fetchInitialData } from '@c15t/nextjs';
+// In a Server Component — do NOT await
+const ssrData = fetchInitialData({
+  backendURL: 'https://your-instance.c15t.dev',
+  debug: process.env.NODE_ENV === 'development',
+});
+```
+> ℹ️ **Info:**
+> Do not await fetchInitialData() in Server Components. Pass the Promise directly to your client component so Next.js can stream the page while the consent data loads in parallel.
+>
+> ℹ️ **Info:**
+> For fetchInitialData(), prefer a direct backend URL such as https\://your-instance.c15t.dev. For browser-side calls from the provider, C15tPrefetch, and other client runtime work, prefer a same-origin /api/c15t rewrite. See Optimization for the full decision guide.
+>
+> ℹ️ **Info:**
+> Need fully static routes? Use C15tPrefetch in your layout. Matching prefetched data is consumed automatically by the runtime instead of using fetchInitialData(). See Optimization.
+### How Streaming Works
+The diagram below shows how the prefetch avoids blocking the page render. The server fires the `/init` request and immediately starts streaming HTML — the resolved consent data is sent as a later chunk once the backend responds.
+```mermaid
+sequenceDiagram
+    participant SC as Server Component
+    participant NR as Next.js Runtime
+    participant BR as Browser
+    participant BE as c15t Backend
+    SC->>BE: fetchInitialData() → GET /init
+    Note right of SC: Returns a Promise - (not awaited)
+    SC->>NR: Render page tree - (Promise passed as prop)
+    NR->>BR: Stream initial HTML
+    BR->>BR: Hydrate — no consent data yet
+    BE-->>NR: /init response resolves
+    NR->>BR: Stream resolved data chunk
+    BR->>BR: Provider receives SSR data - skips client-side /init fetch
+```
+### Options
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|nextCache|NextCacheOptions \|undefined|Optional Next.js cache controls for SSR init requests.|-|Optional|
+#### `nextCache` NextCacheOptions
+Optional Next.js cache controls for SSR init requests.
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|revalidateSeconds|number \|false \|undefined|Cache lifetime in seconds for the Next.js data cache. Set to false to disable Next.js caching for this call.|-|Optional|
+### Return Value
+Returns `Promise<SSRInitialData | undefined>`. The data includes the init response (jurisdiction, translations, consent model) and GVL data when IAB is configured.
+### Passing SSR Data to the Provider
+Pass the unresolved Promise to the provider's `ssrData` option via a client component:
+```tsx title="components/consent-manager/index.tsx"
+'use client';
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/nextjs';
+import type { InitialDataPromise } from '@c15t/nextjs';
+export default function ConsentManager({
+  children,
+  ssrData,
+}: {
+  children: ReactNode;
+  ssrData?: InitialDataPromise;
+}) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        ssrData,
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+```tsx title="app/layout.tsx"
+import { fetchInitialData } from '@c15t/nextjs';
+import ConsentManager from '@/components/consent-manager';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const ssrData = fetchInitialData({
+    backendURL: 'https://your-instance.c15t.dev',
+  });
+  return (
+    <html lang="en">
+      <body>
+        <ConsentManager ssrData={ssrData}>
+          {children}
+        </ConsentManager>
+      </body>
+    </html>
+  );
+}
+```
+## How Headers Are Resolved
+Unlike `@c15t/react/server` where you must pass headers manually, `fetchInitialData` uses `next/headers` to automatically resolve the incoming request headers. This means geo-location headers from Vercel, Cloudflare, or AWS CloudFront are forwarded to the c15t backend without any extra configuration.
+|Header|Source|Contains|
+|--|--|--|
+|`cf-ipcountry`|Cloudflare|Country code|
+|`x-vercel-ip-country`|Vercel|Country code|
+|`x-amz-cf-ipcountry`|AWS CloudFront|Country code|
+|`x-vercel-ip-country-region`|Vercel|Region code|
+|`accept-language`|Browser|Language preference|
+|`x-forwarded-host`|Proxy|Original host|
+|`x-forwarded-for`|Proxy|Client IP|
+## Advanced: Using @c15t/react/server Directly
+For advanced use cases (custom server frameworks, edge functions, or non-standard header resolution), the underlying utilities from `@c15t/react/server` are available:
+```ts
+import {
+  fetchSSRData,
+  extractRelevantHeaders,
+  normalizeBackendURL,
+  validateBackendURL,
+} from '@c15t/react/server';
+```
+See the [React Server-Side Utilities](/docs/frameworks/react/server-side) docs for full API details.
+## Debugging SSR
+Use the [useSSRStatus](/docs/frameworks/next/hooks/use-ssr-status) hook on the client to verify SSR data was consumed:
+```tsx
+import { useSSRStatus } from '@c15t/nextjs';
+function DebugSSR() {
+  const { ssrDataUsed, ssrSkippedReason } = useSSRStatus();
+  if (ssrDataUsed) return <span>SSR hydration successful</span>;
+  return <span>SSR skipped: {ssrSkippedReason ?? 'unknown'}</span>;
+}
+```