---
title: Pages Router
description: Set up c15t in the Next.js Pages Router with Inth, a build-time
  policy manifest, getServerSideProps and consent-gated scripts.
group: frameworks
lastModified: "2026-10-10T16:01:45+01:00"
---
## Before you start

This guide uses [Inth](https://inth.com) for policies and consent records. Your
Next.js build bundles the project's public policy manifest. The server resolves consent
for each visitor in `getServerSideProps`, through `withConsentProps`. The browser sends consent choices to
Inth.

A [self-hosted backend](/docs/self-host/quickstart) uses the same files with
its own URL. [Offline mode](/docs/frameworks/next/data-fetching-reference#offline-configuration)
keeps policy in your code and choices in the browser, with no consent records.
Not recommended for production environments.

This setup needs a Next.js server. For `output: 'export'`, follow
[static export](/docs/frameworks/next/static-export).
[Rendering and deployment](/docs/frameworks/next/rendering) compares every
path.

Location-based policies need trusted location headers from your host. Without
them, c15t applies your unknown-location rule. See
[Forward geography headers](/docs/frameworks/next/geography-headers) before
you deploy.

## Install c15t and configure your backend

[Create an Inth project](https://inth.com), set its policy rules and add your
site's origin to its trusted origins. Copy the project's backend URL.

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

## Set the backend URL

Set `NEXT_PUBLIC_C15T_BACKEND_URL` to your project's backend URL, including
any path prefix, in `.env.local` and in your host's build settings:

```sh title=".env.local"
NEXT_PUBLIC_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `NEXT_PUBLIC_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `NEXT_PUBLIC_C15T_BACKEND_URL` wins.

Next.js inlines `NEXT_PUBLIC_` variables at build time, so the build, the
server and the browser use the same URL, and changing the variable on a built
app has no effect until you rebuild.

## Bundle the manifest during builds

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Wrap your Next.js config in `withConsentManifest`. An existing config object
or function goes in as the first argument, unchanged:

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

// Reads NEXT_PUBLIC_C15T_BACKEND_URL, like defineConsentConfig.
export default withConsentManifest(nextConfig);
```

`next build`, `next dev` and `next typegen` fetch `${backendURL}/manifest` and
write the policy to `node_modules/.cache/c15t/`, outside your source tree, so
there is nothing to keep out of Git. `next start` serves the built snapshot and
fetches no policy. Without a `backendURL` option, the build reads the
`backendURL` in `c15t.config.ts`, which defaults to
`NEXT_PUBLIC_C15T_BACKEND_URL`, then `NEXT_PUBLIC_INTH_PROJECT_URL`, so saves
and the snapshot point at the same
project.

The wrapper reads `c15t.config.ts` the way Next.js reads `next.config.ts`, and
skips the fetch for `mode: hosted()`, `mode: offline()`,
`manifest({ snapshot })` and `manifest({ source: 'runtime' })`, which read no
build-time manifest. Those builds never contact the backend. If the file can't
be read at build time, for example because it imports something Node can't
load, the build warns and fetches as for `manifest()`.

The wrapper also finds `c15t.config.ts` (or `.mts`, `.js`, `.mjs`) at the
project root, next to `next.config.ts`, and points `c15t/generated` at the
cache, in Turbopack and webpack. `ConsentRoot`, `resolveConsent` and the
consent route read both without an import. Server code that needs the
snapshot itself imports `snapshot` from `c15t/generated`. Only server
bundles get the snapshot: in a browser bundle,
`c15t/generated` imports `server-only`, so importing it from a client
component fails the build. The wrapper also adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages`, so Pages Router server bundles see the
aliases. A package you list in `serverExternalPackages` stays external: it
reads no `c15t.config.ts` and fetches the policy at runtime.

If the fetch fails, `next build` stops. `next dev` logs a warning instead, and
`snapshot` is `undefined`, so the server fetches and caches the policy at
runtime, as with
[runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
To let a build continue the same way, set `onBuildError: 'runtime'`, or run it
with `C15T_ON_BUILD_ERROR=runtime`:

```ts title="next.config.ts"
export default withConsentManifest(nextConfig, { onBuildError: 'runtime' });
```

A missing backend URL counts as a failed fetch. The build skips the fetch and
leaves `snapshot` `undefined` when the backend URL is relative, or when the
config sets `output: 'export'`, which has no server to use the snapshot. With
`onBuildError: 'fail'`, a relative URL stops the build. A static export always
skips the fetch.

`withConsentProps()` and `createPagesConsentRoute()` read the snapshot
through the same alias. The wrapper adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages` for this: the Pages Router leaves
dependencies external on the server otherwise, and an external package does
not see the alias.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

To apply policy edits without a rebuild, set
`mode: manifest({ source: 'runtime' })` in `c15t.config.ts`. The server then
uses [runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
Keep `withConsentManifest`, which also finds `c15t.config.ts`.

## Add the consent config

Create `c15t.config.ts` at the project root, next to `next.config.ts`:

```ts title="c15t.config.ts"
import { posthog } from '@c15t/integrations/posthog';
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	routePrefix: '/api/c15t',
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

`withConsentManifest` finds the file, so `ConsentRoot`, `withConsentProps` and
the consent route read it without an import. The file is bundled into the
browser as well as the server, so it can hold `scripts` but must hold no
secrets. The config sets no `mode`, so it uses `manifest()`; see
[consent modes](/docs/concepts/modes).

`routePrefix` names the consent route below. Pages without
`getServerSideProps` resolve consent in the browser through it.

PostHog waits for measurement consent here. Replace `phc_your_project_key`
with your project key, or use the [integration](/docs/integrations/overview)
your application needs.

## Add the consent API route

Create one catch-all API route under `routePrefix`:

```ts title="pages/api/c15t/[...c15t].ts"
import { createPagesConsentRoute } from 'c15t/next/pages';

export default createPagesConsentRoute();
```

It answers `GET /api/c15t/init` and `GET /api/c15t/manifest` from the bundled
snapshot. With runtime fetching, it fetches `${backendURL}/manifest` and
caches the public policy. Any other path under `/api/c15t` returns 404, and
methods other than `GET` and `HEAD` get `405`. The file must be named
`[...c15t].ts`; for another name, pass the parameter as the second argument,
such as `createPagesConsentRoute({}, 'path')` for `[...path].ts`.

## Mount one root for every page

There is no c15t stylesheet to import. The components render their own rules
as `<style>` elements, so no stylesheet request holds back the first paint.
With Tailwind CSS 3, import `c15t/next/styles.css` yourself and set
`styles: false` in `ConsentRoot`'s `options`, as
[Customize](/docs/frameworks/next/customize#load-the-stylesheet-yourself)
shows.

Render `ConsentRoot` in `_app.tsx`. It reads the state a page resolved on the
server from `pageProps.consent`:

```tsx title="pages/_app.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ConsentPageProps } from 'c15t/next/pages';
import type { AppProps } from 'next/app';

import '@/styles/globals.css';

const App = ({ Component, pageProps }: AppProps<ConsentPageProps>) => (
	// Pages without getServerSideProps resolve consent in the browser.
	<ConsentRoot state={pageProps.consent}>
		<Component {...pageProps} />
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentRoot>
);

export default App;
```

A page with `withConsentProps` supplies `consent`. On any other page,
including static and `getStaticProps` pages, `consent` is undefined, and the
browser asks `/api/c15t/init` after hydration. That route resolves the
bundled policy with the browser request's location headers.

## Resolve consent in getServerSideProps

Export `withConsentProps()` from `c15t/next/pages` as the page's
`getServerSideProps`:

```tsx title="pages/index.tsx (partial)"
import { withConsentProps } from 'c15t/next/pages';

export const getServerSideProps = withConsentProps();
```

It resolves the visitor's consent from `c15t.config.ts` and adds it to the
page's props as `consent`, with `undefined` fields removed, as Next.js
requires. The page renders the banner in the server HTML, and the browser
applies the same state without an `/init` request.

A page with its own `getServerSideProps` passes it in:

```ts title="pages/posts/[slug].tsx (partial)"
export const getServerSideProps = withConsentProps(async ({ params }) => ({
	props: { post: await loadPost(params?.slug) },
}));
```

Consent resolves while the page's function runs, and its `redirect` and
`notFound` results pass through unchanged. `resolveConsent` options, such as
`timeoutMs`, go in the second argument.

Add `withConsentProps` to every page that should render consent on the
server. Do not resolve consent in `getStaticProps`. It runs without the
visitor's request, so it cannot read their cookies or location. If the
snapshot is missing and the runtime manifest request fails or takes longer
than `timeoutMs`, 500 ms by default, the page renders without a policy and the
browser retries after hydration.

## Use backend init instead of the manifest

Set `mode: hosted()` in `c15t.config.ts` and remove `routePrefix` and
`pages/api/c15t/[...c15t].ts`. Keep `withConsentManifest`, which finds the
config. With `hosted()` it downloads no manifest, so `next build` does not
contact the backend. `_app.tsx` and the pages stay the same. `withConsentProps` and the browser now call
`${backendURL}/init`, and consent choices still go to
`${backendURL}/subjects`. For a browser-only setup with no server work, follow
[client-side initialization](/docs/frameworks/next/client-side).

Keeping browser saves on your origin with
[`proxy: true`](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin) is optional with
either source.

## Verify the setup

Start the production build with `next build` and `next start`, then open a
page that exports `withConsentProps` in a fresh browser session with DevTools
open.

1. View the page source. It contains `data-testid="consent-banner-root"`.
2. Under an opt-in policy, the Network panel shows no PostHog request. Click
   **Reject All** and reload. The banner stays closed and PostHog does not
   load.
3. Open **Privacy settings** and turn on **Analytics** (the `measurement`
   category). PostHog loads.
4. Navigate to another page with a Next.js `Link` and reopen
   **Privacy settings**. The choice is still selected.
5. Open a static page directly. It shows the same choice, resolved in the
   browser through `/api/c15t/init`.

Pages with `withConsentProps` make no `/init` request, and choices post to
`${backendURL}/subjects`. [Script loading](/docs/frameworks/next/scripts)
explains each vendor's loading and revocation behavior, and
[the consent checks](/docs/guides/verify-consent) cover the release checklist.