@c15t/nextjs 2.2.0 → 3.0.0-alpha.0

package/docs/frameworks/next/server-side.md

@@ -1,173 +1,140 @@
 ---
-title: Server-Side Data Fetching
-description: Pre-fetch consent data in Server Components with fetchInitialData
-  for dynamic Next.js routes.
+title: Server rendering and hydration
+description: Resolve consent on the server, choose what waits for the result,
+  and preserve the same state through hydration.
 group: frameworks
 ---
-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.
+## Choose when consent resolves
 
-> ℹ️ **Info:**
-> SSR hydration is part of the initialization flow. When SSR data is available, the client skips the API fetch entirely.
+Fetching and rendering are separate choices. The examples here keep the shared
+`consentConfig` and manifest route from the
+[App Router guide](./app-router.md).
 
-```ts
-import { fetchInitialData } from '@c15t/nextjs';
-```
+| Rendering path                             | Pass to `ConsentRoot` as `state`               | What the visitor receives                                                                       |
+| ------------------------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Await consent                              | The resolved `resolveConsent` result           | The consent subtree renders after resolution. A surrounding Suspense fallback may stream first. |
+| Stream while consent resolves              | The `resolveConsent` promise                   | The page renders immediately; the browser initializes consent when the result arrives.          |
+| [Browser initialization](./client-side.md) | `state={{}}`, with the shared URLs in `config` | The browser initializes after mount; the initial HTML has no resolved consent prompt.           |
 
-## fetchInitialData
+Client Components can still be prerendered by Next.js. Browser initialization
+describes where consent resolves, not whether the component produces server HTML.
 
-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.
+## Use the helper for your router
 
-```ts title="app/layout.tsx"
-import { fetchInitialData } from '@c15t/nextjs';
+| Router        | Server helper import | Request context                        |
+| ------------- | -------------------- | -------------------------------------- |
+| App Router    | `c15t/next/server`   | Next.js request cookies and headers    |
+| Pages Router  | `c15t/next/pages`    | `req` passed from `getServerSideProps` |
+| Static export | No request helper    | Browser initialization                 |
 
-// In a Server Component — do NOT await
-const ssrData = fetchInitialData({
-  backendURL: 'https://your-instance.c15t.dev',
-  debug: process.env.NODE_ENV === 'development',
-});
-```
+For complete setup files, follow [App Router](./app-router.md),
+[Pages Router](./pages-router.md) or
+[static export](./static-export.md).
+Pages Router must await prefetch inside `getServerSideProps` before serializing
+props. The streaming examples on this page are for App Router.
 
-> ⚠️ **Warning:**
-> 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<br/>(not awaited)
-    SC->>NR: Render page tree<br/>(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,<br/>skips client-side /init fetch
-```
+## Stream the page while consent resolves
 
-### Options
+The App Router guide awaits `resolveConsent` inside `Suspense` by
+default and offers this promise form as the streaming alternative. Pass the
+promise from a synchronous layout to the script-owning client wrapper. This
+partial example keeps that wrapper:
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`FetchInitialDataOptions\`|
-|Source Path|\`./packages/nextjs/src/types.ts\`|
+```tsx
+import { resolveConsent } from 'c15t/next/server';
+import { consentConfig } from '../c15t.config';
+import { Consent } from '../components/consent';
 
-\*ExtractedTypeTable: Could not extract "FetchInitialDataOptions" from "./packages/nextjs/src/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+// Inside the existing synchronous layout:
+const state = resolveConsent({ config: consentConfig });
 
-### Return Value
+<Consent state={state}>{children}</Consent>
+```
 
-Returns `Promise<SSRInitialData | undefined>`. The data includes the init response (jurisdiction, translations, consent model) and GVL data when IAB is configured.
+This promise form does not render consent UI on the server. For server-rendered
+consent UI, await the result as shown below.
 
-### Passing SSR Data to the Provider
+Keep the shared config and manifest route from that guide. This form also
+works with `cacheComponents: true`. Request helpers still need a visitor request;
+passing a promise does not make this a static-export setup.
 
-Pass the unresolved Promise to the provider's `ssrData` option via a client component:
+## Await consent inside Suspense
 
-```tsx title="components/consent-manager/index.tsx"
-'use client';
+If the consent subtree should wait for resolution, move it into an async Server
+Component under `Suspense`. With `cacheComponents: true`, awaiting request data
+directly in the root layout without this boundary causes a build error.
 
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/nextjs';
-import type { InitialDataPromise } from '@c15t/nextjs';
+This is the default root layout from the App Router guide. Keep its shared
+`c15t.config.ts`, manifest route and script-owning `Consent` wrapper:
+
+```tsx title="app/layout.tsx"
+import { Suspense } from 'react';
+import type { ReactNode } from 'react';
+import { Consent } from '../components/consent';
+import { resolveConsent } from 'c15t/next/server';
+import { consentConfig } from '../c15t.config';
+import './globals.css';
+
+async function ResolvedConsent({ children }: { children: ReactNode }) {
+  const state = await resolveConsent({ config: consentConfig });
 
-export default function ConsentManager({
-  children,
-  ssrData,
-}: {
-  children: ReactNode;
-  ssrData?: InitialDataPromise;
-}) {
   return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        ssrData,
-      }}
-    >
-      <ConsentBanner />
-      <ConsentDialog />
-      {children}
-    </ConsentManagerProvider>
+    <Consent state={state}>{children}</Consent>
   );
 }
-```
-
-```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',
-  });
 
+export default function RootLayout({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <body>
-        <ConsentManager ssrData={ssrData}>
-          {children}
-        </ConsentManager>
+        <Suspense fallback={null}>
+          <ResolvedConsent>{children}</ResolvedConsent>
+        </Suspense>
       </body>
     </html>
   );
 }
 ```
 
-## How Headers Are Resolved
+This example waits to render the children inside `ResolvedConsent`. The outer
+shell and fallback can stream first, so awaiting does not guarantee a resolved
+prompt in the first HTML response. Use the promise form when the page should
+render while consent is pending.
 
-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.
+## Preserve the server result
 
-|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|
+`resolveConsent` restores records and resolves policy for the request.
+With `manifestURL`, it resolves the configured manifest. With only `backendURL`,
+it calls `${backendURL}/init`. Changing when you await the helper does not change
+which fetching path it uses.
 
-## Advanced: Using @c15t/react/server Directly
+Pass the result intact to `state` and keep the same shared URLs in `config`.
+Do not turn allowed categories into new saved choices or emit a choice event
+during hydration. Keep one `ConsentRoot` mounted across navigation.
 
-For advanced use cases (custom server frameworks, edge functions, or non-standard header resolution), the underlying utilities from `@c15t/react/server` are available:
+With resolved server state, `Frame` renders its placeholder or permitted content
+in the server HTML and reuses that state during hydration. It does not need to
+wait for the browser to mount before showing the placeholder. The default
+placeholder is visible immediately, without a fade-in animation.
 
-```ts
-import {
-  fetchSSRData,
-  extractRelevantHeaders,
-  normalizeBackendURL,
-  validateBackendURL,
-} from '@c15t/react/server';
-```
+A resolved policy can satisfy browser initialization without another request.
+If prefetch fails or returns only baseline records, the browser can retry.
+Until resolution succeeds, optional permissions remain denied and consent UI
+stays hidden. See [Troubleshooting](./troubleshooting.md).
 
-See the [React Server-Side Utilities](/docs/frameworks/react/server-side) docs for full API details.
+`resolveConsent()` called without `config` or `backendURL` only reads request
+cookies, location, language and privacy signals. It makes no backend request
+and does not resolve policy. Pass `config` when rendering needs the resolved
+policy.
 
-## Debugging SSR
+## Cache policy data without sharing visitor state
 
-Use the [useSSRStatus](/docs/frameworks/next/hooks/use-ssr-status) hook on the client to verify SSR data was consumed:
+A manifest is public policy configuration. Resolved init data, stored records
+and personalized HTML belong to a visitor. Keep them out of shared caches unless
+you provide appropriate isolation. Test more than one visitor and location.
 
-```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>;
-}
-```
+See [Optimization](./optimization.md) for cache settings and the
+[fetching reference](./api-reference/data-fetching.md#geography-and-privacy-signals)
+for trusted location headers. Same-origin rewrites are optional and do not enable
+server rendering.

package/docs/frameworks/next/static-export.md

@@ -0,0 +1,164 @@
+---
+title: Static export
+description: Add c15t to output export without request helpers or a local API server.
+group: frameworks
+---
+
+[Create an Inth project](https://inth.com) and use its backend endpoint in
+this guide. Configure the project's policy rules and allowed app origins first.
+
+## Use a browser ConsentRoot
+
+A Next.js static export has no runtime server for `/api/c15t`, Next.js rewrites or
+request cookies. Point the browser at an absolute consent backend URL. Static
+hosting does not require browser-only consent storage.
+
+| Package manager | Command            |
+| :-------------- | :----------------- |
+| npm             | `npm install c15t` |
+| pnpm            | `pnpm add c15t`    |
+| yarn            | `yarn add c15t`    |
+| bun             | `bun add c15t`     |
+
+```ts title="next.config.ts"
+import type { NextConfig } from 'next';
+
+const config: NextConfig = { output: 'export' };
+export default config;
+```
+
+```tsx title="components/consent.tsx"
+'use client';
+
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentDialogLink,
+  ConsentRoot,
+} from 'c15t/next';
+
+export function Consent({ children }: { children: ReactNode }) {
+  const backendURL = process.env.NEXT_PUBLIC_C15T_BACKEND_URL;
+  if (!backendURL) throw new Error('Set NEXT_PUBLIC_C15T_BACKEND_URL');
+  return (
+    <ConsentRoot state={{}} backendURL={backendURL}>
+      {children}
+      <ConsentBanner />
+      <ConsentDialog />
+      <ConsentDialogLink>Privacy settings</ConsentDialogLink>
+    </ConsentRoot>
+  );
+}
+```
+
+Add c15t to the global stylesheet shared by your app. With Tailwind CSS 4,
+keep its import first:
+
+```css title="styles/globals.css"
+@import 'tailwindcss';
+@import 'c15t/next/styles.css';
+```
+
+Without Tailwind, omit its import. For Tailwind CSS 3, use the
+[separate stylesheet recipe](./styling/overview.md#stylesheet).
+Keep any existing app styles and adjust the imports below to their location.
+
+For App Router, mount the wrapper in the root layout:
+
+```tsx title="app/layout.tsx"
+import type { ReactNode } from 'react';
+import { Consent } from '../components/consent';
+import '../styles/globals.css';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return <html lang="en"><body><Consent>{children}</Consent></body></html>;
+}
+```
+
+For Pages Router, mount the same wrapper in `_app.tsx`:
+
+```tsx title="pages/_app.tsx"
+import type { AppProps } from 'next/app';
+import { Consent } from '../components/consent';
+import '../styles/globals.css';
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Consent><Component {...pageProps} /></Consent>;
+}
+```
+
+The imports assume `app/`, `pages/` and `components/` are at the project root.
+Adjust them if your project uses `src/`.
+
+Set `NEXT_PUBLIC_C15T_BACKEND_URL` when building the site. Next.js embeds public
+environment values into the browser bundle, so changing this URL requires a new
+build. Configure the exported site's origin in the backend's trusted origins.
+
+## Test the exported files
+
+Run your production build and serve the generated `out/` directory with a
+static server. A Next.js development server can hide accidental dependencies on
+API routes. Inspect Network for failed same-origin `/api/c15t` calls, then test
+reject, reload, preference changes and an unavailable backend using
+[verification](../../guides/verify-consent.md).
+
+## What happens before initialization?
+
+The exported HTML cannot contain a choice resolved for an individual visitor.
+The browser restores valid records and resolves the policy. Until a policy
+resolves, optional permissions remain denied and the consent UI stays hidden.
+Do not insert an unconditional analytics script into the exported HTML to work
+around that pending state.
+
+## Use an external manifest when you need client resolution
+
+Regular Inth `/init` is the simpler hosted path for static export. If you want
+the browser to resolve a manifest instead, change the existing `ConsentRoot`
+to use a consent config. Set `NEXT_PUBLIC_C15T_MANIFEST_URL` to a reachable
+absolute manifest endpoint and keep the same backend URL for saves.
+
+This is a partial change to `components/consent.tsx`:
+
+```tsx
+import { defineConsentConfig } from 'c15t/next';
+
+const backendURL = process.env.NEXT_PUBLIC_C15T_BACKEND_URL;
+const manifestURL = process.env.NEXT_PUBLIC_C15T_MANIFEST_URL;
+if (!backendURL || !manifestURL) throw new Error('Set the public consent URLs');
+
+const consentConfig = defineConsentConfig({ backendURL, manifestURL });
+
+// Keep the existing children, banner, dialog and preferences link.
+<ConsentRoot state={{}} config={consentConfig}>
+  {children}
+</ConsentRoot>
+```
+
+Do not set `initURL` to a local Next.js API route in an export. The browser
+loads the manifest resolver lazily and resolves unknown geography unless your
+application supplies location through a separate design. It cannot read a
+server's geographic request headers. Ensure the manifest and record endpoints
+allow requests from the exported site's origin.
+
+For build-time policy snapshots, `c15t/next/static` exports
+`loadStaticManifest`, `createStaticManifestModule` and
+`createStaticConsentResolver`. A generated manifest contains public policy,
+not a visitor's resolved choice. `createStaticConsentResolver` returns a
+synchronous `initial` result and a `resolved` promise that can use `geo` or a
+`geoURL`. These helpers do not mount a provider, persist choices or configure
+consent writes for you. Plan that wiring and policy refresh before choosing a
+build-time snapshot; publishing new policy may require a rebuild.
+
+Never bake a build machine's location or cookies into a shared static page.
+Unknown geography does not make every regional rule applicable.
+
+## Use offline mode for local-only records
+
+Not recommended for production environments. Use it for local development and
+tests; a static production site can still connect to Inth.
+
+If the site deliberately needs no consent backend, use the explicit
+[offline boundary example](./api-reference/data-fetching.md#offline-configuration).
+It resolves bundled rules and stores choices in the browser. Static hosting
+alone is not a reason to give up Inth policy management and consent records.