Skip to content
ConsentLayer

Introduction

This page describes what ConsentLayer does, how the documentation is organized, what runs in the browser and on the server, and what each entry point adds to your bundle.

What is ConsentLayer?

Section titled “What is ConsentLayer?”

ConsentLayer is an analytics library that routes your events to GA4, Meta Pixel, PostHog, Sentry and the other supported providers, and decides from the visitor’s consent which of those providers may load and receive data. You create one instance with createAnalytics(), track events through it once, and each provider translates them into its own format.

Every provider declares a requiredConsent: one of the built-in categories preferences, analytics and marketing, a custom category you declare, 'none', or a function of the current consent. ConsentLayer runs a provider’s load hook, which injects the vendor’s script or imports its SDK, only once that requirement is met. Page views, events, identity and errors are delivered only while it is met, and withdrawing consent runs the provider’s teardown hook. The exceptions are explicit: providers with 'none', such as Sentry error reporting and cookieless PostHog, run without consent, and GA4 and Meta load before consent only when you set loadBeforeConsent: true to rely on the vendor’s own consent mode. The Providers guide lists the category of each provider.

import { createAnalytics } from 'consentlayer'
import { ga4 } from 'consentlayer/providers/ga4'
import { meta } from 'consentlayer/providers/meta'


export const analytics = createAnalytics({
  providers: [ga4({ measurementId: 'G-XXXXXXX' }), meta({ pixelId: '123456789012345' })],
})


analytics.track('purchase', { transaction_id: 'o1', value: 30, currency: 'EUR' })

Creating the instance loads nothing. Providers start when analytics.boot() runs, which <AnalyticsProvider> calls for you. Calls made before then are held, up to 100, and delivered when boot completes to the providers whose requirement is met at that moment.

The npm package ships no consent banner. useConsentController() exposes the banner’s state and actions, and the Consent UI guide provides a recipe to copy and restyle, so the markup, wording and translations stay in your codebase. On a site without a build step, the script tag loads ConsentLayer and a ready-made banner from a CDN.

Where consent is stored and how it is announced

The visitor’s choice is a ConsentState object with one boolean per category. It is stored in localStorage under consentlayer_consent, with the date it was made and, if you set one, your policy version, so ConsentLayer can ask again later. On every change, ConsentLayer assigns it to window.CONSENTLAYER_CONSENT and dispatches a consentlayer:consent DOM event whose detail is the new state, so scripts outside ConsentLayer can react to it. All three names derive from names.prefix.

On startup, analytics.consent.bootstrap() reads the stored choice. If there is none, it asks each consent adapter in order, such as the Shopify Customer Privacy adapter, and keeps the first non-null answer. If neither yields a choice, consent stays null, which satisfies no requirement other than 'none', and <AnalyticsProvider> shows the banner. It shows the banner too when the stored choice is stale: made under an earlier major policy version or longer ago than maxAgeDays. The full sequence is described in Consent.

How to use the docs

Section titled “How to use the docs”

The docs are organized into the following sections:

Use the sidebar to navigate between sections, or search with Ctrl+K or Cmd+K.

For AI assistants and coding agents, the docs are also published as plain Markdown: /llms.txt lists them, /llms-full.txt holds every page, and /llms-small.txt leaves out the internals, the migration guide and the changelog.

Browser and server

Section titled “Browser and server”

ConsentLayer runs on both sides of your application:

  • In the browser, createAnalytics() holds the consent state and the providers. It loads each provider when its requirement is met, translates your events into each provider’s format, and routes errors from captureError and the window’s error and unhandledrejection events to the providers that report errors, Sentry and PostHog.
  • On the server, consentlayer/server provides web-standard route handlers of the form (request: Request) => Promise<Response>. createAnalyticsHandler receives the events the browser forwards when you set server.endpoint and sends them to the Meta Conversions API, the TikTok Events API or a server-side GTM container. sendServerEvent sends events that never pass through the browser, such as a confirmed payment from a webhook, to those destinations and to the GA4 Measurement Protocol. createConsentHandler appends each consent choice to your database and sets a signed cookie that proves it.

The browser forwards an event to the server only while analytics or marketing is granted, and the server sends it only to the destinations whose own category is granted in the event’s consent: marketing for Meta and TikTok, and analytics for server-side GTM and GA4. Each event carries one ID, the eventId you pass to track() or a generated UUID, which is used both in the browser and on the server, so Meta can deduplicate an event it receives from both.

Bundle size

Section titled “Bundle size”

Each entry point is a separate module, the package is marked free of side effects so bundlers drop the exports you don’t import, and provider SDKs, Sentry Session Replay and Sentry tracing are loaded with dynamic import() only when they are first needed. These are the sizes of the current release, minified and brotli-compressed, each including the shared code it imports, so they don’t add up exactly. Vendor SDKs, whether installed from npm or loaded from the vendor’s CDN, are not included.

Entry point Size
consentlayer, everything 7.0 kB
consentlayer, only createAnalytics 5.6 kB
consentlayer/auto-tracking 0.9 kB
consentlayer/react 2.1 kB
consentlayer/next 1.6 kB
consentlayer/vue 2.2 kB
consentlayer/svelte 1.9 kB
consentlayer/sveltekit 2.0 kB
consentlayer/solid 2.1 kB
consentlayer/solidstart 2.2 kB
consentlayer/angular 2.2 kB
consentlayer/providers/ga4 1.9 kB
consentlayer/providers/gtm 1.8 kB
consentlayer/providers/meta 1.8 kB
consentlayer/providers/tiktok 1.8 kB
consentlayer/providers/contentsquare 1.1 kB
consentlayer/providers/posthog 1.0 kB
consentlayer/providers/sentry 0.9 kB
consentlayer/server 2.4 kB
consentlayer/server/meta 1.3 kB
consentlayer/server/tiktok 1.2 kB
consentlayer/server/sgtm 1.0 kB
Script tag, consentlayer.global.js 14.0 kB
Script tag banner, consentlayer-banner.global.js 1.7 kB

The Svelte figures count the MetaPixelNoscript and GtmNoscript components as source, which your Svelte compiler builds. consentlayer/nuxt runs at build time, and adds consentlayer/vue to your application. To keep your own bundle small, see Reduce bundle size.