Data fetching reference

Config reference

defineConsentConfig from c15t/next declares the app's consent setup in c15t.config.ts at the project root. withConsentManifest in next.config.ts finds the file and hands it to ConsentRoot, resolveConsent, withConsentProps, createConsentRoute and createPagesConsentRoute, so the app never imports it. For help choosing a setup, start with rendering and deployment. Requires Next.js 15 or 16 (next ^15.0.0 || ^16.0.0).

The file is bundled into the browser as well as the server, so it can hold functions such as scripts but must hold no secrets. Read server-only values, such as a token for forwardHeaders, in server code.

Values can be absolute HTTP or HTTPS URLs or paths beginning with /. Server helpers resolve relative paths against the incoming request's host. If your server answers requests for any Host header, such as a Node server exposed directly or a proxy that forwards Host from its default virtual host, use an absolute backendURL. A relative one resolves against whatever Host the request sent, so the request would choose the origin the server fetches.

defineConsentConfig returns a frozen object. On the server, which includes withConsentManifest reading the file at build time, it validates first and throws a TypeError with one of these messages. Browser bundles skip the checks, so they add no bytes there:

Protocol-relative and bare URLs are rejected because the server helpers would resolve them against the request host and reach an unintended origin.

Do I need the consent route?

Not when every page resolves consent on the server. The root layout or withConsentProps supplies the initial policy directly to the browser.

Add the route when some pages render without server state: static, ISR or 'use cache' pages in the App Router, or Pages Router pages without withConsentProps. Set routePrefix: '/api/c15t' in c15t.config.ts and mount the route:

import { createConsentRoute } from 'c15t/next/api';

export const { GET } = createConsentRoute();

For Pages Router, use this file instead:

import { createPagesConsentRoute } from 'c15t/next/pages';

export default createPagesConsentRoute();

The route answers GET ${routePrefix}/init by resolving the bundled manifest with the browser request's location headers, so those pages get the same policy a server render would. It also answers GET ${routePrefix}/manifest for manifest({ resolve: 'browser' }).

Without routePrefix, browser initialization calls the backend's /init. See geography and privacy signals.

Mode combinations

Hosted and manifest modes submit choices to ${backendURL}/subjects. Offline mode uses browser persistence only. A prepared server result satisfies the first browser initialization; the browser column describes what happens when initialization is needed, including recovery after the server render failed.

The browser loads only the code of the mode it runs. With manifest() resolved on the server, the snapshot, the resolver and other languages stay out of the browser bundle; see what each mode adds to first-load JavaScript.

Switch to regular backend init

Set mode: hosted() in c15t.config.ts. The client-side guide has the complete config. For server rendering, keep the layout from your router guide. resolveConsent will call backend /init per request.

Remove the consent route if no page needs it, unless proxy: true sends browser saves through it. See optimization.

Server helper options

resolveConsent is the one server helper. c15t/next/server exports it for the App Router, where the default request context reads next/headers and calls await connection() from next/server before reading the clock. c15t/next/pages exports the same function for the Pages Router, taking the Node req instead, and withConsentProps wraps it as a getServerSideProps. All of them accept the options in this section; the Pages Router entry replaces only the request adapter.

resolveConsent() needs no options: it reads c15t.config.ts and the snapshot withConsentManifest downloaded. What it does depends on the mode. manifest() resolves policy from the snapshot, or from ${backendURL}/manifest through the in-process cache without one. hosted() calls ${backendURL}/init. offline(), or no backend URL at all, makes no network request and returns cookie- and header-only state; see cookie-only state.

resolveConsent options

resolveConsent throws when the request adapter's headers() or cookies() rejects (the default adapter rejects outside a request scope), and when your onError callback throws. Thrown URL resolution, network, timeout and policy resolution errors are handled: they return the same baseline state as the cookie-only call, with stored records, geography, language and GPC from the request but no resolved policy. The page still renders and the browser initializes consent on mount. Non-2xx responses from backend /init are failures too, so a 500 renders the baseline rather than throwing. A successful response whose body reports policyResolution.status: 'failed', for example an unsupported policy contract, is different: that failed resolution is kept as the prepared state, the browser does not re-initialize on mount, and the consent UI stays hidden until the cause is fixed.

Slow or unavailable backends

resolveConsent waits at most timeoutMs (500 ms by default) for policy. A warm manifest cache answers in about a millisecond, and a cold read over a new connection to a hosted backend usually takes a few hundred. When the budget runs out, the render uses the baseline state: no consent UI in the server HTML, optional categories denied, and consent-gated scripts and iframes blocked. ConsentRoot then initializes in the browser and shows the banner once the backend answers, retrying failed attempts with backoff.

The manifest request does not stop when the render gives up. It keeps running, up to the cache's 5 second request timeout, and stores the manifest for later renders. Pass waitUntil so serverless platforms keep it alive after the response.

Server manifest reads, in resolveConsent and in the route handlers, share these rules:

• Concurrent requests for the same manifest URL share one upstream request.
• A render that joins a request already in flight waits only for what is left of that request's timeoutMs.
• After a failed request, with no usable copy cached, that URL is not asked again for 1 second. Each further failure doubles the wait, up to 5 seconds. Requests in between fail at once with a ManifestUnavailableError whose reason is 'backoff', so a struggling backend sees at most one request per URL per server instance in each interval.
• A stale copy is served only inside the backend's stale-while-revalidate window, while one background request refreshes it. Past that window the read waits for the backend like a miss and never falls back to the expired copy.

In the App Router, both resolveConsent and createConsentRoute pass next: { revalidate: 300 } to upstream manifest fetches. Next.js's Data Cache can satisfy an in-process cache miss, including on a new server instance when your host provides a shared cache. A manifestURL pointing directly at the backend uses these same cache layers. The consent route also provides a cacheable response for browsers and your CDN.

Pages Router helpers keep the in-process cache, but ordinary Pages Router fetches do not use the App Router Data Cache. A build-time snapshot avoids manifest cache misses in both routers and stays fixed until rebuilding.

Absolute http(s) URLs are used as given. resolveConsent resolves a /-relative backendURL or manifestURL against the request's host header. A domain name resolves over https. localhost, an IP address or a single-label host such as app:3000 resolves over http. The x-forwarded-host, x-forwarded-proto, forwarded and referer headers are ignored, because any client can send them and the /init call carries the visitor's consent cookie to the resolved host. When no host header is available, resolveConsent reports the error and returns the baseline state.

A render never fetches your own consent route: a URL on the request's origin under the config's routePrefix. resolveConsent reports the URL and returns the baseline state instead. Keep the config's backendURL absolute, and use proxy: true to keep the browser on your origin.

Any other same-origin backendURL is a backend reached through your app, such as /api/c15t with a rewrite or a mounted @c15t/backend. resolveConsent calls its /init like any backend. That request goes back through your own server, which costs a second function invocation on serverless hosts and fails behind deployment protection; the render then returns the baseline state and the browser resolves the policy. Pass the backend's own URL to skip the hop. If the prefix reaches no backend and a page answers instead, that page's resolveConsent sees the request came from a render and does not fetch again.

Behind a proxy that sets x-forwarded-host and x-forwarded-proto and drops the values a client sends, pass trustForwardedHeaders: true to resolve against them instead. Use https for any production backendURL. Over plain HTTP to anything but a loopback host, the /init call carries no cookie, no forwardHeaders and no client IP.

Forwarded headers differ by path, and only what the backend needs travels:

• The backend /init call carries the resolved x-c15t-country, x-c15t-region, accept-language and sec-gpc, the user-agent, and the experiment arm while the visitor has no stored choice. Over https or to a loopback host it also carries the consent cookie (cookieName, never the rest of the cookie jar), any forwardHeaders, and with trustForwardedHeaders the visitor IP as x-forwarded-for. It is sent with cache: 'no-store'.
• The manifest request carries only the headers named in forwardHeaders, because the manifest is public policy data.

Cookies are still read locally on both paths to restore records.

An inline snapshot, including the one withConsentManifest downloaded, is never refreshed. The manifest transport returns the object as given instead of fetching it, so the snapshot is the source of truth for that request rather than a cache seed. A stale snapshot resolves stale policy until the application ships a new one. One request can still happen: when the inline manifest has iab.enabled: true with an iab.gvl reference and the matched rule uses the iab model, the transport fetches the Global Vendor List with the fetch option, and a blocked network there also falls back to the baseline. backendURL is still required because choices post to ${backendURL}/subjects.

onError replaces the default logging entirely. Without it, production deployments render the baseline silently; pass onError to report failures to your monitoring. cookieName must match the client storageKey for stored choices to be restored at all: with a mismatch the server supplies empty records, the provider treats them as prepared and skips browser hydration, so the visitor's existing choice stays ignored for the whole mount, not only at first paint.

Cookie-only state

With mode: offline(), or when no backend URL is configured anywhere, resolveConsent returns state that needs the visitor's stored records but no resolved policy. It makes no network request. It reads the request and returns a JSON-serializable ConsentState with initialRecords, initialPrivacySignals.gpc, now and, when any value was detected, initialOverrides with country, region and language. It does not set cookies and does not cache across requests. Only these options apply:

The cookie header is read from headers().get('cookie') first and from request.cookies() only when that header is absent. Country and region come from the headers listed in geography and privacy signals.

Types

Pages Router differences

withConsentProps(getServerSideProps?, options?) from c15t/next/pages is a getServerSideProps that resolves consent and adds it to the page's props as consent. It wraps the page's own getServerSideProps when given; consent resolves while it runs, and its redirect and notFound results pass through. options takes every option in the App Router table except request. The state is round-tripped through JSON, because Next.js rejects undefined prop values such as an absent GPC signal.

c15t/next/pages also exports resolveConsent with the Node request in place of the request adapter. resolveConsent({ req, ...options }) accepts every option in the App Router table except request; req is the request from getServerSideProps or an API route. Its result can hold undefined fields, so round-trip it through JSON.parse(JSON.stringify(result)) before returning it as a prop, or use withConsentProps, which does that for you.

createPagesRequestContext(req) builds the request adapter itself. Headers are converted to Web Headers, and cookies are read from the cookie header. Use it when calling the c15t/next/server helper from a custom server or test harness where next/headers is unavailable:

import type { IncomingMessage } from 'node:http';

import { createPagesRequestContext } from 'c15t/next/pages';
import { resolveConsent } from 'c15t/next/server';

export function resolveRequestConsent(req: IncomingMessage) {
	return resolveConsent({ request: createPagesRequestContext(req) });
}

Route handler options

createConsentRoute options

createConsentRoute(options?) from c15t/next/api returns GET for one catch-all route, such as app/api/c15t/[...c15t]/route.ts. GET answers /init and /manifest under the route; every other path answers 404. With proxy, it also returns POST, PATCH, PUT, DELETE and OPTIONS, and forwards the other consent paths to the backend. Everything defaults to c15t.config.ts and the snapshot withConsentManifest downloaded.

With no snapshot, manifestURL wins over backendURL. URLs are resolved per request, so a missing or invalid value fails the request rather than the build: with no snapshot and neither backendURL nor manifestURL, the handler throws. A /-relative value is resolved against the origin of request.url, which Next.js builds itself. Forwarding headers are read only with trustForwardedHeaders: true. A relative value still points the handler at your own app, so keep upstream URLs absolute; otherwise the consent route fetches itself.

A /-relative manifestURL on the config's mode names the route itself, so the handler ignores it. Keep the config's backendURL absolute. To keep the browser on your origin, set proxy: true rather than a relative backendURL.

The handlers are built on the consent route handler in @c15t/core/server, which the TanStack Start, SvelteKit, Astro and Nuxt adapters share, so the rules below are the same in every framework.

GET ${routePrefix}/init resolves the build snapshot or runtime cached manifest with the request's geography, language and GPC headers and responds with cache-control: private, no-store and x-c15t-policy-contract: 1. The payload echoes the inputs it used as resolvedOverrides and resolvedPrivacySignals. The browser sends its overrides and policy contract as the country, region, gpc and contract query parameters, which win over the matching x-c15t-* headers. When the request declares a different policy contract in either form, the response keeps the translations and UI data but sets policyResolution to status: 'failed' with reason: 'unsupported-contract'. Whenever the resolution is not matched, the payload carries no policySnapshotToken, gvl, gvlReference, cmpId or customVendors. Requests that declare no contract are treated as compatible.

With a snapshot, GET ${routePrefix}/manifest returns the complete snapshot as JSON with status 200. It makes no upstream request, adds no cache or validator headers and does not answer If-None-Match with 304 or slice by language.

With runtime fetching, GET ${routePrefix}/manifest forwards the upstream cache-control, etag, last-modified and content-language headers, adds content-type: application/json and an age computed from the in-process cache, and answers a matching If-None-Match with 304. It never invents a cache-control header the upstream did not send. The only query parameter passed upstream is a language that looks like a language tag, lower-cased; every other parameter is dropped, so a visitor's query string neither reaches the backend nor adds cache entries.

With runtime fetching, when the manifest cannot be read and backendURL is set, GET ${routePrefix}/init asks the backend's own GET /init instead, forwarding only the geography, language and GPC headers. This covers backends without /manifest. It happens for a 404 and for the first failure of a failing backend, not for every request while the manifest cache backs off. Otherwise the handler rejects and Next.js answers 500.

fetchGvl runs inside the init path only when the manifest has iab.enabled: true, the manifest includes an iab.gvl reference, and the resolved policy matched with model: 'iab'. It receives the reference, the fetch option, and the language taken from the first segment of the resolved translations language (en when empty). The default fetcher caches the vendor list in process and aborts the upstream request after five seconds. A fetched list becomes a gvlReference and a small banner summary in the serialized payload. A null result keeps IAB unavailable. A rejected or timed-out fetch fails the request rather than answering gvl: null, because the browser reads null as "IAB is off" and would show a policy that requires the TCF without it. With routePrefix, the browser reads the list from that same-origin route; otherwise it uses the manifest's public list URL. The banner shows the same purpose names and vendor count on the server and during hydration. A client-only vendors allowlist on the IAB config makes that server summary unusable, so the banner waits for the full list. Filter vendors on the server when the banner must render immediately.

createPagesConsentRoute(options?, param?) from c15t/next/pages accepts the same options except proxy and returns the default export of a catch-all pages/api route, pages/api/c15t/[...c15t].ts. param names the catch-all parameter and defaults to c15t; a file with another name throws @c15t/nextjs: createPagesConsentRoute found no `c15t` catch-all parameter. Name the file [...c15t].ts or pass its parameter name. Because a pages/api default export receives every method, requests other than GET and HEAD are answered with 405 and an allow: GET header before the wrapped handler runs. The bridge rebuilds the request URL from the host header, over http for localhost, IP and single-label hosts and https otherwise, and reads forwarding headers only with trustForwardedHeaders: true.

Manifest request resolution

The App Router and Pages Router manifest setups use this flow:

1. next build bundles the backend's /manifest response as a snapshot. With manifest({ source: 'runtime' }) instead, the server fetches the absolute backend's /manifest endpoint and caches the public policy data.
2. resolveConsent() resolves policy from that snapshot or cache with the current request's inputs and restores valid consent cookies.
3. ConsentRoot receives that result as state and reads the rest from c15t.config.ts. Hydration preserves the resolved state.
4. If browser initialization is needed, it asks ${routePrefix}/init, whose route resolves the same snapshot on the server, or ${backendURL}/init without routePrefix. manifest({ resolve: 'browser' }) resolves in the browser instead.
5. Browser choices post to ${backendURL}/subjects.

A warm policy cache avoids backend /init during request resolution. The app may still read its consent route, cold caches fetch upstream data, and choices still reach the backend. IAB policies can also require a Global Vendor List fetch. See manifest caching for cache settings, and rendering and deployment for awaiting or streaming prefetch results.

Static manifest helpers

c15t/next/static exports loadStaticManifest, createStaticManifestModule, createStaticConsentResolver and resolveUnknownLocationInit for resolving consent from a manifest bundled at build time, for example in an output: 'export' site. The two resolvers come from c15t/static, which c15t/tanstack-start/static re-exports too.

• createStaticManifestModule({ manifestURL }) fetches a manifest and returns TypeScript source for a module you write to disk and import.
• loadStaticManifest fetches and returns the manifest object.
• createStaticConsentResolver({ manifest, geo, geoURL }) returns a synchronous initial result and a resolved promise. Without geo, or when a geoURL returns no location, it uses the manifest's unknown-location policy: its fallback rule, else its default rule. That is the same policy the server helpers apply when a request has no location headers. Rules scoped to a country or region never apply to an unknown location.
• resolveUnknownLocationInit(manifest, { language, gpc }) returns that unknown-location result on its own.

A manifest with neither a fallback rule nor a default rule cannot resolve an unknown location. The resolvers then return a failed result with the reason insufficient-inputs, and the client applies its safe fallback. Give your policy a fallback rule before you bundle it.

A generated manifest contains public policy, not a visitor's choice. The helpers do not mount a provider, persist choices or send consent to the backend. You wire them into a custom transport passed as options.mode, and publishing new policy needs a rebuild. The static export guide uses backend /init instead, which needs none of this. Never bake a build machine's location or cookies into a shared static page.

A static export can also resolve a manifest in the browser without these helpers. Set mode: manifest({ resolve: 'browser', manifestURL }) in c15t.config.ts, with an absolute manifestURL the browser can fetch from your site's origin. Browser manifest resolution has no location input, so every visitor gets your unknown-location rule.

Geography and privacy signals

Server manifest resolution reads location headers from the hosting platform. It recognizes country headers such as cf-ipcountry and x-vercel-ip-country, and region headers such as cf-region-code and x-vercel-ip-country-region. The application overrides x-c15t-country and x-c15t-region take precedence. Only trusted infrastructure should supply location overrides in production.

Request helpers also read language and GPC. Missing location stays unknown; the resolver does not infer country from the Next.js server's IP. Test unknown country and region against your configured policy rules.

Browser manifest resolution uses location overrides from prefetch, inputs or geoURL. Without them, a location-based policy asks the backend's /init. The consent route reads geographic headers on the server and keeps resolver code and translations out of browser initialization.

Offline configuration

Not recommended for production environments. Use offline mode for local development, tests or demos that do not need backend records.

Set mode: offline() in c15t.config.ts. It needs no backend URL:

import { defineConsentConfig, offline } from 'c15t/next';

export default defineConsentConfig({ mode: offline() });

Keep your layout. resolveConsent() then makes no network request and the browser resolves the rules after hydration. offline() from c15t/next is data, so the offline rules load with import() only in apps that use them.

The default local policy pack handles missing geography; offline mode does not perform IP lookup. Supply policyRules to replace that pack when your local policy needs different behavior. Browser persistence stores choices, but this setup has no backend record service. See transport choices for the tradeoffs.

Offline mode runs only when you choose it. ConsentRoot throws when manifest() or hosted() finds no backend URL: not in the mode, the config or NEXT_PUBLIC_C15T_BACKEND_URL. That happens only without a c15t.config.ts, because defineConsentConfig throws without a backend URL. See troubleshooting.

Authenticated hosted vendor lists

When hosted resolveConsent() forwards the consent cookie or additional request headers, or uses a custom fetch, it retains the fetched vendor list in server state. The browser cannot replay a private server fetch. This fallback preserves consent loading and vendor filtering without copying credentials into the page. Its payload size is unchanged from inline GVL loading. For compact pages with private upstreams, expose the public list through the consent route with routePrefix.