@c15t/nextjs 2.2.0 → 3.0.0-alpha.0

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

@@ -0,0 +1,296 @@
+---
+title: Pages Router
+description: Set up Pages 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 setup below uses `getServerSideProps` for request-specific consent. Pages
+without prefetch initialize in the browser through the same `ConsentRoot`.
+
+## 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`     |
+
+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',
+});
+```
+
+## Add the manifest API route
+
+The Pages Router adapter reads `C15T_BACKEND_URL`, falling back to the
+`NEXT_PUBLIC_C15T_BACKEND_URL` configured above. If you set both, use the same
+absolute backend endpoint.
+
+```ts title="pages/api/c15t/manifest.ts"
+import { createPagesApiHandlers } from 'c15t/next/pages';
+
+export default createPagesApiHandlers().manifest;
+```
+
+The manifest route caches public policy data. Server prefetch resolves it
+using the visitor's request. Consent submissions go directly to `backendURL`.
+
+The following imports assume `pages/` is at the project root. Adjust them if you
+use `src/pages/`.
+
+## 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.
+
+## Keep one root in the app
+
+Add c15t to your global stylesheet. 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 import below to their location.
+
+```tsx title="pages/_app.tsx"
+import type { AppProps } from 'next/app';
+import type { ConsentRootProps } from 'c15t/next';
+import { Consent } from '../components/consent';
+import '../styles/globals.css';
+
+type ConsentPageProps = {
+  consentState?: ConsentRootProps['state'];
+};
+
+export default function App({ Component, pageProps }: AppProps<ConsentPageProps>) {
+  return (
+    <Consent state={pageProps.consentState ?? {}}>
+      <Component {...pageProps} />
+    </Consent>
+  );
+}
+```
+
+`consentState` is the visitor's resolved state; `consentConfig` contains the
+shared URLs. Without page prefetch, the browser loads the manifest and resolves
+policy locally. 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).
+Consent submissions go to `${backendURL}/subjects` on the configured backend.
+
+## Prefetch for a server-rendered page
+
+Use `c15t/next/pages` with the `req` from `getServerSideProps`. The App Router
+helper reads a different request context and must not be used here.
+
+```tsx title="pages/index.tsx"
+import type { GetServerSideProps } from 'next';
+import type { ConsentRootProps } from 'c15t/next';
+import { resolveConsent } from 'c15t/next/pages';
+import { consentConfig } from '../c15t.config';
+
+type PageProps = { consentState: ConsentRootProps['state'] };
+
+export const getServerSideProps: GetServerSideProps<PageProps> = async ({ req }) => {
+  const state = await resolveConsent({ config: consentConfig, req });
+  return {
+    props: {
+      consentState: JSON.parse(
+        JSON.stringify(state)
+      ) as PageProps['consentState'],
+    },
+  };
+};
+
+export default function Home() {
+  return <main>Your page</main>;
+}
+```
+
+The JSON round-trip removes `undefined` fields, such as an absent GPC signal,
+because Next.js rejects them in `getServerSideProps` props.
+
+Repeat prefetch on pages that need request-specific initial HTML. Do not use
+`getStaticProps` to resolve visitor cookies or geography: it runs without the
+visitor's request. Keep the shared URL configuration consistent across pages.
+
+## Verify entry and navigation
+
+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.
+
+Load a server-rendered page directly, reject, and reload. Then navigate without
+a full reload and reopen preferences. The mounted boundary should retain the
+choice. Also test direct entry to a statically generated page; it uses browser
+manifest resolution, so verify your unknown-location rule.
+
+Confirm the server reads `/manifest` instead of the backend `/init` and choices
+reach `${backendURL}/subjects`. See
+[Optimization](./optimization.md) for caching, or compare
+alternatives in [data fetching](./data-fetching.md). For a deployment with no Next.js server, use
+[static export](./static-export.md) and remove local API routes.
+
+## 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/quickstart.md

@@ -1,145 +1,44 @@
 ---
 title: Quickstart
-description: Add consent management to your Next.js app in under 5 minutes.
-variants:
-  - value: javascript
-    href: /docs/frameworks/javascript/quickstart
-    label: JavaScript
-  - value: react
-    href: /docs/frameworks/react/quickstart
-    label: React
-  - value: next
-    href: /docs/frameworks/next/quickstart
-    label: Next.js
+description: Add c15t consent management to Next.js with Inth, with setup guides
+  for the App Router, the Pages Router and static export.
 group: frameworks
 ---
-## Via CLI
 
-<PackageCommandTabs command="@c15t/cli" />
+## Choose your setup
 
-## Manual Installation
+We recommend [Inth](https://inth.com) for policy management and consent records.
+For Next.js server deployments, the guides use cached manifests: your server
+reuses public policy data and resolves consent for each visitor. Static exports
+initialize through Inth in the browser.
 
-1. **Install package**
+| Your deployment                       | Start here                          |
+| ------------------------------------- | ----------------------------------- |
+| App Router with a Next.js server      | [App Router](./app-router.md)       |
+| Pages Router with a Next.js server    | [Pages Router](./pages-router.md)   |
+| Either router with `output: 'export'` | [Static export](./static-export.md) |
 
-2. **Import styles** Import the prebuilt component stylesheet in your app-level CSS entrypoint. This is required for styled components to render correctly.
+Each guide includes installation, backend prerequisites, consent-gated scripts
+and a persistent preferences link. Start with the guide for your deployment; you do not need to read
+the fetching reference first.
 
-   ```css
-   @import "@c15t/nextjs/styles.css";
-   ```
+[Self-hosting](https://c15t.com/docs/self-host/quickstart) uses the same setup with your own
+backend. [Offline mode](./api-reference/data-fetching.md#offline-configuration)
+resolves bundled policy and keeps choices in browser storage, with no backend
+requests or records. Not recommended for production environments.
 
-   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.With Tailwind v4, keep c15t at the end of the top-level @import block so Fumadocs, tw-animate-css, and other preset imports do not override c15t theme tokens.
+## Other setup choices
 
-   > ℹ️ 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.
+For a smaller hosted setup without server prefetch or local API routes, use
+[client-side initialization](./client-side.md). Consent resolves
+in the browser, so the initial HTML has no resolved consent prompt.
 
-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.
+[Data fetching](./data-fetching.md) compares manifests and regular
+backend initialization. [Server rendering](./server-side.md)
+explains when to await consent or stream the page while it resolves. Same-origin
+[rewrites](./optimization.md) are optional optimizations.
 
-   ```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.
-   >
-   > ⚠️ Warning:
-   > 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:
-
-   1. A **consent banner** appears at the bottom of the page
-   2. Clicking **"Customize"** opens a dialog with toggles for each consent category
-   3. After 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:
-
-<PackageCommandTabs mode="install" command="@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.
-
-<PackageCommandTabs command="@c15t/cli skills" />
-
-See [AI Agents](/docs/ai-agents) for bundled package docs and agent skills.
-
-## Next steps
-
-* [Optimization](/docs/frameworks/next/optimization)
-* [Script Loader](/docs/frameworks/next/script-loader)
-* [Styling](/docs/frameworks/next/styling/overview)
-* [Consent Categories](/docs/frameworks/next/concepts/consent-categories)
-* [Components](/docs/frameworks/next/components/consent-banner)
-* [AI Agents](/docs/ai-agents)
+Try the [runnable Next.js example](https://c15t.com/docs/examples) with both routers, a gated
+YouTube video, PostHog, X Pixel and custom banner designs. The router guides use
+the same script configuration. After setup, [verify requests and persistence](../../guides/verify-consent.md);
+a visible banner alone does not establish that analytics wait for consent.