@c15t/nextjs 2.2.1 → 3.0.0-alpha.0

package/docs/frameworks/next/app-router.md

@@ -0,0 +1,403 @@
+---
+title: App Router
+description: Set up App Router with Inth, cached manifests and consent-gated scripts.
+group: frameworks
+---
+
+## Before you start
+
+This guide uses [Inth](https://inth.com) with cached manifests. Your Next.js
+server reuses public policy data and resolves consent for each visitor. The
+browser sends consent submissions to Inth.
+
+You can use a [self-hosted backend](https://c15t.com/docs/self-host/quickstart) with the same
+configuration and your own endpoint. [Offline mode](./api-reference/data-fetching.md#offline-configuration)
+uses bundled policy and browser storage without backend records. Not recommended
+for production environments.
+
+This setup needs a Next.js server. For `output: 'export'`, follow
+[static export](./static-export.md). For a smaller setup with no
+local API routes, use [client-side initialization](./client-side.md).
+Same-origin [rewrites](./optimization.md) are optional.
+
+Location-based policies need trusted location headers from your host. Without
+them, c15t uses your unknown-location rule. Check the supported
+[geography headers](./api-reference/data-fetching.md#geography-and-privacy-signals)
+before deploying.
+
+The default layout awaits consent on the server inside a `Suspense` boundary,
+so the server renders the resolved banner into the response instead of
+deciding in the browser. You can also
+[stream the page while consent resolves](#stream-the-page-while-consent-resolves)
+or initialize in the browser. Awaiting has a cost; see
+[what server prefetch costs](#what-server-prefetch-costs) before deploying.
+
+## Install c15t and configure your backend
+
+[Create an Inth project](https://inth.com), configure its policy rules and allow
+your app's origin. Copy its backend endpoint for the upstream configuration.
+
+If you chose self-hosting, complete the
+[backend quickstart](https://c15t.com/docs/self-host/quickstart) and use its public endpoint in
+the steps below. Offline setups do not need an endpoint; use the
+[offline example](./api-reference/data-fetching.md#offline-configuration).
+
+| Package manager | Command            |
+| :-------------- | :----------------- |
+| npm             | `npm install c15t` |
+| pnpm            | `pnpm add c15t`    |
+| yarn            | `yarn add c15t`    |
+| bun             | `bun add c15t`     |
+
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
+
+With Tailwind CSS 4, add the prebuilt stylesheet to your global CSS after
+Tailwind so its component layer follows Tailwind's:
+
+```css title="app/globals.css"
+@import 'tailwindcss';
+@import 'c15t/next/styles.css';
+```
+
+For Tailwind CSS 3, use the [Tailwind 3 stylesheet recipe](./styling/overview.md#stylesheet)
+instead. It loads `c15t/next/styles.tw3.css` between the `components` and
+`utilities` directives to prevent Tailwind from purging c15t selectors.
+
+The layouts on this page import `./globals.css`; without Tailwind the same
+`@import` line goes at the top of whatever global stylesheet the layout loads.
+
+Set `NEXT_PUBLIC_C15T_BACKEND_URL` to the absolute endpoint supplied by Inth or
+your self-hosted backend, including any path prefix. This is a public endpoint,
+not a secret. Configure the backend to allow your app's origin.
+
+## Share the consent URLs
+
+Create this file at the project root. Set `manifestURL` explicitly to select
+manifest resolution.
+
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
+
+const backendURL = process.env.NEXT_PUBLIC_C15T_BACKEND_URL;
+if (!backendURL) throw new Error('Set NEXT_PUBLIC_C15T_BACKEND_URL');
+
+export const consentConfig = defineConsentConfig({
+  backendURL,
+  manifestURL: '/api/c15t/manifest',
+});
+```
+
+## Serve the manifest route
+
+The built-in handler reads the absolute upstream URL from `C15T_BACKEND_URL`,
+falling back to `NEXT_PUBLIC_C15T_BACKEND_URL` from the setup above. If you set
+both, point them at the same backend.
+
+```ts title="app/api/c15t/manifest/route.ts"
+export { manifestGET as GET } from 'c15t/next/api';
+```
+
+The manifest handler caches public policy data. Server prefetch resolves it
+using the visitor's request. Consent submissions go directly to `backendURL`.
+
+The paths below assume `app/` is at the project root. Adjust imports if you use
+`src/app/`.
+
+## Register scripts in a client wrapper
+
+The [runnable Next.js example](https://c15t.com/docs/examples) uses PostHog for measurement and
+X Pixel for marketing. Set `NEXT_PUBLIC_POSTHOG_KEY` and
+`NEXT_PUBLIC_X_PIXEL_ID` to your own project identifiers before building.
+`NEXT_PUBLIC_POSTHOG_HOST` optionally selects your PostHog region's API host.
+Omit a vendor's ID to leave that integration disabled, or replace its helper
+with the [integration](../../integrations/overview.md) your application uses. Include the
+measurement and marketing categories in your policy for these two vendors.
+
+Create `lib/scripts.ts` with the example's script configuration:
+
+```ts title="lib/scripts.ts"
+import { posthog } from '@c15t/scripts/posthog';
+import { xPixel } from '@c15t/scripts/x-pixel';
+import type { Script } from 'c15t';
+
+export const posthogConfigured = Boolean(process.env.NEXT_PUBLIC_POSTHOG_KEY);
+export const xPixelConfigured = Boolean(process.env.NEXT_PUBLIC_X_PIXEL_ID);
+
+export const scripts: Script[] = [];
+
+if (process.env.NEXT_PUBLIC_POSTHOG_KEY) {
+	scripts.push(
+		posthog({
+			apiHost: process.env.NEXT_PUBLIC_POSTHOG_HOST,
+			id: process.env.NEXT_PUBLIC_POSTHOG_KEY,
+			initOptions: { cookieless_mode: 'never' },
+			loadMode: 'after-consent',
+		})
+	);
+}
+
+if (process.env.NEXT_PUBLIC_X_PIXEL_ID) {
+	scripts.push(xPixel({ pixelId: process.env.NEXT_PUBLIC_X_PIXEL_ID }));
+}
+```
+
+PostHog waits for measurement consent here. `cookieless_mode: 'never'` disables
+cookieless capture after rejection. X Pixel waits for marketing consent. Remove
+any existing loader for these vendors, including `next/script` and tag-manager
+entries, so each integration loads once.
+
+Create this client wrapper. It keeps scripts and browser callbacks in the client
+while the router supplies the visitor's resolved state through `state`:
+
+```tsx title="components/consent.tsx"
+'use client';
+
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentDialogLink,
+  ConsentRoot,
+} from 'c15t/next';
+import type { ConsentRootProps } from 'c15t/next';
+import { consentConfig } from '../c15t.config';
+import { scripts } from '../lib/scripts';
+
+export function Consent({
+  children,
+  state,
+}: {
+  children: ReactNode;
+  state: ConsentRootProps['state'];
+}) {
+  return (
+    <ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+      {children}
+      <ConsentBanner />
+      <ConsentDialog />
+      <footer>
+        <ConsentDialogLink>Privacy settings</ConsentDialogLink>
+      </footer>
+    </ConsentRoot>
+  );
+}
+```
+
+`ConsentRoot` already provides the consent runtime. Mount this wrapper once;
+do not add a second provider. Keep your site's content and footer inside it.
+
+## Start consent resolution in the root layout
+
+Await `resolveConsent` in an async Server Component and mount that
+component inside `Suspense`. The helper reads request cookies and geographic
+headers, resolves policy from the manifest and returns the visitor's resolved
+state, which the `Consent` wrapper passes to `ConsentRoot` as `state`.
+
+```tsx title="app/layout.tsx"
+import { Suspense } from 'react';
+import type { ReactNode } from 'react';
+import { resolveConsent } from 'c15t/next/server';
+import { consentConfig } from '../c15t.config';
+import { Consent } from '../components/consent';
+import './globals.css';
+
+async function ResolvedConsent({ children }: { children: ReactNode }) {
+  const state = await resolveConsent({ config: consentConfig });
+
+  return <Consent state={state}>{children}</Consent>;
+}
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Suspense fallback={null}>
+          <ResolvedConsent>{children}</ResolvedConsent>
+        </Suspense>
+      </body>
+    </html>
+  );
+}
+```
+
+With this layout, the server renders the consent subtree only after policy has
+resolved, so the banner arrives already decided and does not change after
+hydration. Because the boundary uses `fallback={null}`, Next.js may stream the
+shell first and the consent subtree a moment later in the same response. A
+returning visitor whose request cookie carries a valid stored choice sees no
+banner; an expired choice, a choice recorded under a different policy
+fingerprint, or one that no longer covers every required category prompts
+again. Location rules apply when your host supplies trusted geography
+headers. The [runnable Next.js example](https://c15t.com/docs/examples) uses this awaited form.
+
+If the manifest request fails, `resolveConsent` returns a baseline
+state without a resolved policy and logs the failure outside production. The
+page still renders, and the browser resolves policy after hydration, so on that
+request a new visitor sees the prompt appear late. Pass `onError` to report
+these failures; see [troubleshooting](./troubleshooting.md).
+
+The page content waits with the consent subtree. Because `{children}` sits
+inside `ResolvedConsent` and the fallback is `null`, a slow manifest response
+leaves the whole page blank until the helper returns or its 10 second fetch
+timeout fires and the baseline renders. A warm manifest cache makes this a few
+milliseconds; a cold cache pays the backend round trip. If the site cannot
+accept that, use the [streaming form](#stream-the-page-while-consent-resolves),
+which renders the shell immediately.
+
+Keep the c15t stylesheet in `globals.css` rather than importing
+`c15t/next/styles.css` from a layout or component. Tailwind CSS 4 declares its
+cascade layers in that file; when the c15t stylesheet is bundled separately
+and lands first, Tailwind's preflight sits above the c15t component layer and
+strips the banner's padding, borders and button styles.
+
+The `Suspense` boundary is required with `cacheComponents: true`: awaiting
+request data directly in the root layout without it fails the build. Without
+`cacheComponents`, the boundary is still safe to keep. If `next dev` reports an
+unstable `Date.now()` during prerendering, see
+[troubleshooting](./troubleshooting.md#why-does-nextjs-report-an-unstable-datenow-during-prerendering).
+
+## What server prefetch costs
+
+`resolveConsent` reads request cookies and headers through
+`next/headers`. Without `cacheComponents`, this makes routes under the layout
+dynamically rendered. With `cacheComponents` enabled, Next.js can prerender
+and cache the static shell outside `Suspense`, while the visitor-specific
+consent subtree resolves and streams per request.
+
+The first request on a new server instance has an empty manifest cache and
+waits for the upstream `/manifest` fetch. In the local benchmark with 150 ms of
+simulated backend latency, the single cold sample measured a 252 ms time to
+first byte. A build-time manifest seed to remove this cold start is planned in
+[c15t/c15t#1096](https://github.com/c15t/c15t/issues/1096).
+
+With a warm manifest cache in the same local benchmark (awaited SSR, new
+visitors, 150 ms simulated backend latency), time to first byte was 7.4 ms
+median and 15.2 ms at p95 across 10 samples, and the banner markup was present
+in the first HTML. The benchmark layout awaits the helper without a `Suspense`
+boundary, so it does not measure the streaming behavior of the recipe on this
+page, and its 28 ms banner metric is a post-hydration visibility probe, not
+first paint. See the
+[benchmark results](https://github.com/c15t/c15t/tree/ccfe906682ba06cef7b56a16cc8fd10728df77d3/benchmarks/reports/next-manifest-2026-09-10)
+for conditions.
+
+The resolved consent subtree contains one visitor's state. Do not put that
+subtree, or the complete response containing it, in a shared cache. Public
+manifests and the prerendered static shell can be cached separately. See
+[cache policy data without sharing visitor state](./server-side.md#cache-policy-data-without-sharing-visitor-state).
+
+When the page shell must not wait for consent, use the
+[streaming form](#stream-the-page-while-consent-resolves); it still reads the
+request, so the route stays dynamic. When the site must stay fully static, use
+[client-side initialization](./client-side.md).
+
+## Stream the page while consent resolves
+
+To render the page shell before consent resolves, keep the root layout
+synchronous and pass the pending promise from `resolveConsent` to
+`state`. `ConsentRoot` accepts either the resolved result or its promise.
+
+```tsx title="app/layout.tsx"
+import type { ReactNode } from 'react';
+import { resolveConsent } from 'c15t/next/server';
+import { consentConfig } from '../c15t.config';
+import { Consent } from '../components/consent';
+import './globals.css';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  const state = resolveConsent({ config: consentConfig });
+
+  return (
+    <html lang="en">
+      <body><Consent state={state}>{children}</Consent></body>
+    </html>
+  );
+}
+```
+
+This promise form does not render the banner in the initial HTML. The provider
+mounts with a provisional policy, consent surfaces stay hidden until the
+promise resolves, and the browser then applies the server result. Keep this
+layout synchronous, including when Next.js `cacheComponents` is enabled; the
+form works with `cacheComponents: true`. Request helpers still need a request
+context even though the layout passes a promise. See
+[server rendering](./server-side.md) for the comparison of
+rendering paths.
+
+## Verify the manifest path
+
+For an opt-in policy, reject and confirm neither configured vendor loads. Allow
+measurement only: PostHog can load, while X Pixel stays blocked. Revoke
+measurement from Privacy settings and check PostHog's capture is disabled.
+See [script loading](./script-loader.md) for vendor-specific
+loading and revocation behavior.
+
+Inspect server requests and confirm that consent resolution reads the manifest
+instead of calling Inth `/init`. Warm requests should reuse policy data according
+to its cache headers. Consent choices should post to `${backendURL}/subjects`.
+
+Test a new visitor, a returning rejection and two locations. Missing geographic
+headers must follow your unknown-location rule. See
+[fetching reference](./api-reference/data-fetching.md) for
+location headers and [Optimization](./optimization.md) for cache
+settings. If resolution fails, use
+[Troubleshooting](./troubleshooting.md), then run
+[the consent checks](../../guides/verify-consent.md).
+
+## Initialize in the browser
+
+Keep the shared config and manifest route. Remove the `resolveConsent`
+and `Suspense` imports and the `ResolvedConsent` component, and render the
+wrapper directly with an empty state:
+
+```tsx title="app/layout.tsx"
+import type { ReactNode } from 'react';
+import { Consent } from '../components/consent';
+import './globals.css';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Consent state={{}}>{children}</Consent>
+      </body>
+    </html>
+  );
+}
+```
+
+The browser loads the manifest and resolves policy locally, so the initial
+HTML has no resolved prompt. Without supplied location, geography is unknown.
+For browser initialization with request geography, see the
+[optional local init route](./api-reference/data-fetching.md#do-i-need-the-local-init-route).
+
+## Use regular backend initialization instead
+
+For a complete browser-only setup with hosted records, follow
+[client-side initialization](./client-side.md). It needs no
+local route handlers or server prefetch.
+
+For the smallest hosted configuration, keep only `backendURL` in
+`defineConsentConfig`:
+
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
+
+const backendURL = process.env.NEXT_PUBLIC_C15T_BACKEND_URL;
+if (!backendURL) throw new Error('Set NEXT_PUBLIC_C15T_BACKEND_URL');
+
+export const consentConfig = defineConsentConfig({ backendURL });
+```
+
+This is an alternative to the manifest configuration. Remove the unused local
+manifest route. The existing prefetch and boundary now initialize
+through `${backendURL}/init`; consent saves still use `${backendURL}/subjects`.
+A backend-only config does not enable manifest mode automatically.
+
+Compare the choices in [data fetching](./data-fetching.md), or
+configure cache settings and optional rewrites in
+[Optimization](./optimization.md).

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

@@ -0,0 +1,118 @@
+---
+title: Client-side initialization
+description: Initialize Next.js consent in the browser with one backend URL,
+  without server prefetch or local API handlers.
+group: frameworks
+---
+
+## Choose when consent resolves
+
+Use browser initialization when consent does not need to be resolved in the
+initial HTML. This works with prerendered pages and client navigation. No
+`resolveConsent`, manifest route or rewrite is required for this setup.
+
+Use [server rendering](./server-side.md) when consent UI should
+render on the server after policy resolution, or when resolution should start
+on the server while the page streams.
+
+"Client-side initialization" describes where consent resolves. Next.js can
+still prerender a Client Component's initial markup. Optional permissions stay
+denied and consent UI stays hidden until policy resolution succeeds.
+
+## Configure one backend URL
+
+[Inth](https://inth.com) is recommended for production. A self-hosted c15t
+backend uses the same configuration with its own public endpoint.
+
+| Package manager | Command            |
+| :-------------- | :----------------- |
+| npm             | `npm install c15t` |
+| pnpm            | `pnpm add c15t`    |
+| yarn            | `yarn add c15t`    |
+| bun             | `bun add c15t`     |
+
+Set `NEXT_PUBLIC_C15T_BACKEND_URL` to the absolute public backend endpoint and
+configure your app's allowed origin there. Create this shared file at the
+project root:
+
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
+
+const backendURL = process.env.NEXT_PUBLIC_C15T_BACKEND_URL;
+if (!backendURL) throw new Error('Set NEXT_PUBLIC_C15T_BACKEND_URL');
+
+export const consentConfig = defineConsentConfig({ backendURL });
+```
+
+With the current API, a config containing only `backendURL` initializes through
+`${backendURL}/init` and submits choices to `${backendURL}/subjects`. It does
+not enable manifest resolution or generate API routes. Use
+[data fetching](./data-fetching.md) to choose manifest mode.
+
+## Mount one browser ConsentRoot
+
+```tsx title="components/consent.tsx"
+'use client';
+
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentDialogLink,
+  ConsentRoot,
+} from 'c15t/next';
+import { consentConfig } from '../c15t.config';
+
+export function Consent({ children }: { children: ReactNode }) {
+  return (
+    <ConsentRoot state={{}} config={consentConfig}>
+      {children}
+      <ConsentBanner />
+      <ConsentDialog />
+      <ConsentDialogLink>Privacy settings</ConsentDialogLink>
+    </ConsentRoot>
+  );
+}
+```
+
+`state={{}}` supplies no server-resolved policy. `ConsentRoot` starts hosted
+initialization in the browser. Keep it mounted across client navigation.
+
+For App Router, load the [stylesheet for your Tailwind version](./styling/overview.md#stylesheet)
+from `app/globals.css`, then mount the wrapper in the root layout:
+
+```tsx title="app/layout.tsx"
+import type { ReactNode } from 'react';
+import { Consent } from '../components/consent';
+import './globals.css';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body><Consent>{children}</Consent></body>
+    </html>
+  );
+}
+```
+
+For Pages Router, put the same `Consent` wrapper around
+`<Component {...pageProps} />` in `pages/_app.tsx` and import the stylesheet
+there. No `getServerSideProps` is needed for consent in this variant.
+
+## Optional optimizations and local development
+
+A [same-origin rewrite](./optimization.md) can avoid an
+additional browser connection to the backend domain. It is optional and needs
+a Next.js server or equivalent hosting proxy. A full static export can keep
+the direct public URL shown here.
+
+Offline mode is not recommended for production environments. For local
+development and tests without a backend, use the
+[offline example](./api-reference/data-fetching.md#offline-configuration).
+
+## Verify browser initialization
+
+In a fresh session, confirm the browser calls `/init`, displays the resolved
+prompt, and sends no denied vendor requests. Save a rejection, reload, and
+reopen preferences. The choice should persist. Test a failed backend request
+too; hidden consent UI must not be interpreted as permission.