Integration options

What the integration does

Astro islands never share a component tree, so c15t on Astro has no provider component. The c15t() integration in astro.config.mjs takes its place. It adds four things to your site:

• A middleware that resolves consent for each request into Astro.locals.c15t, which every component reads.
• A page script that starts one consent runtime per page load. Every script and island on the page shares it.
• c15t's styles: base and configured IAB banner rules inline in each page, and dialog rules linked before their surface mounts. On a Tailwind CSS 3 site, the full base and configured IAB stylesheets run through your CSS pipeline instead.
• In manifest() mode, one route at /api/c15t/[...path] that answers /api/c15t/init and /api/c15t/manifest.

import node from '@astrojs/node';
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t from 'c15t/astro';

export default defineConfig({
	adapter: node({ mode: 'standalone' }),
	integrations: [svelte(), c15t()],
	output: 'server',
});

c15t() works with no options: the backend URL comes from PUBLIC_C15T_BACKEND_URL and the mode defaults to manifest(). List the Astro integration of your ui framework before c15t(). Import c15t and the mode helpers from c15t/astro.

Options must survive JSON

The integration serializes its options once at build time and hands the same JSON to the middleware, the components and the browser. Functions, class instances and other live values do not survive that, so c15t() throws when an option holds a function, and names where it is. Put callbacks, vendor helpers from @c15t/integrations and anything else with a function in src/c15t.client.ts, the module clientEntrypoint names.

The options are also written into every page, so keep secrets out of them. The backend URL is public configuration, not a secret.

backendURL

Your Inth or self-hosted backend. The browser saves consent there with POST /subjects, hosted() asks its /init, and manifest() reads ${backendURL}/manifest. It defaults to PUBLIC_C15T_BACKEND_URL, then PUBLIC_INTH_PROJECT_URL, read from the environment or a .env file in the project root when astro.config.mjs loads. A hosted({ backendURL }) of its own wins over both.

On the server, a relative backend URL or manifestURL, such as /api/self-host, resolves against the URL Astro gives the request, Astro.url. c15t does not read x-forwarded-host or other forwarding headers to build it.

mode

Where the visitor's policy comes from. Build it with one of the three helpers from c15t/astro; they return plain data. Without mode, the integration uses manifest().

manifest() accepts:

hosted() accepts:

offline() accepts policyRules, the rules to resolve locally. Without them it resolves the recommended rule pack. Choices persist in the visitor's cookie and localStorage only, and there are no consent records.

manifest() and hosted() stop astro.config from loading without a backend URL, because the server would have no policy to read and the browser nowhere to save consent. A manifest({ snapshot }) needs none for the policy.

Rendering and deployment explains which mode fits which Astro output.

routePrefix

The path of the route the integration injects in manifest() mode: '/api/c15t' by default. One catch-all, ${routePrefix}/[...path], answers ${routePrefix}/init and ${routePrefix}/manifest. A page whose consent changes after it loads, such as after a language change, asks it again.

The route renders on demand, so astro build with manifest() needs a server adapter. manifest({ resolve: 'browser' }) on static output prerenders only ${routePrefix}/manifest. hosted() and offline() inject nothing. Set routePrefix: false to inject nothing in manifest() mode. The browser then asks the backend's /init, not a route of your own. See serve the routes yourself.

Consent and scripts

storageConfig takes storageKey, the cookie and localStorage name, crossSubdomain to share the cookie across subdomains, defaultDomain to set the cookie domain yourself, and defaultExpiryDays, which defaults to a year. The server reads the same cookie name, so set it here and not only in the browser.

Appearance and copy

Customize shows each of these in use.

ui

ui picks the framework that renders the preference dialog and the IAB dialog islands: 'svelte', 'react' or 'vue'. Unset, it is the framework of the one Astro integration among @astrojs/svelte, @astrojs/react and @astrojs/vue your site registers, so the dialog reuses a runtime the site already loads. With none or several of them registered, it is 'svelte'. Install that framework's Astro integration and list it before c15t().

requireUIIntegration, default true, stops the build when the ui framework's Astro integration is missing. Set it to false for a site that never opens a dialog, such as one that only shows a notice.

See Dialog islands and your own islands.

iab

IAB TCF configuration, or false. Takes cmpId, cmpVersion, vendors, publisherCountryCode, publisherRestrictions, gvl, gvlURL and enabled, all plain data. See IAB TCF for each field.

middleware

true (default), false, or an object:

The integration's own route under routePrefix is always skipped. On a skipped route, Astro.locals.c15t is unset and ConsentBanner throws, so skip only routes that render no consent components. See Server API.

clientEntrypoint

A path to a module whose default export adds live values in the browser. A relative path resolves from the project root. Unset, the integration uses src/c15t.client.ts, .js or .mjs when the file exists, so the quickstart sets nothing:

import { posthog } from '@c15t/integrations/posthog';
import type { C15tClientOptionsExtension } from 'c15t/astro';

export default {
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
} satisfies C15tClientOptionsExtension;

The default export is a C15tClientOptionsExtension from c15t/astro:

The browser imports this module into the page script, so every page shares one copy. Keep it small, because it loads on every page.

Errors the integration raises

Troubleshooting has the fix for each.