Configuration

CookiepalConfig is the object baked into the generated bundle and consumed by createConsentManager(config) at runtime. cookiepal build renders it from your local SQLite file; you rarely hand-write one.

Source of truth: packages/consent/src/types.ts.

Top-level shape

interface CookiepalConfig {
  categories: CategoryConfig[];
  banner?: BannerConfig;
  scriptBlocking?: ScriptBlockingRule[];
  integrations?: IntegrationsConfig;
  i18n?: I18n;
  backendURL?: string;
  siteUrl?: string;
  rejectByDefault?: boolean;
  preview?: boolean;
  debug?: boolean;
}

categories is the only required field. Everything else is optional — defaults render a sensible bottom-left box notice with a centered preferences modal.

Categories

interface CategoryConfig {
  slug: string;              // 'necessary', 'analytics', 'advertisement', etc.
  required?: boolean;        // true → cannot be rejected
  cookies?: CookieConfig[];  // optional; populates the preferences table
}

interface CookieConfig {
  name: string;
  domain: string;
  duration: string;          // "2 years", "session", ...
  description?: string;
  locale?: Record<string, string>;
}

The banner has two surfaces: the notice (first-visit prompt) and the preferences dialog (per-category toggles). Each picks a layout via a discriminated union.

interface BannerConfig {
  notice?: NoticeConfig;
  preferences?: PreferencesConfig;
  fab?: { position?: 'left' | 'right' | 'hidden'; customIcon?: string; tooltipLabel?: string };
  accentColor?: string;
  titleColor?: string;
  textColor?: string;
  backgroundColor?: string;
  btnTheme?: 'highlighted' | 'transparent';
  consentExpiry?: number;     // days before re-prompting, default 365
  hideBrand?: boolean;
}

Notice layouts

type NoticeConfig =
  | { layout: 'banner'; edge?: 'top' | 'bottom' } & NoticeBase
  | { layout: 'box'; position?: 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight' } & NoticeBase
  | { layout: 'popup' } & NoticeBase;

Shared fields: title, description, acceptLabel, rejectLabel, customiseLabel, closeLabel, showRejectButton, showCustomiseButton, showCloseButton, cookiePolicyLink.

Preferences layouts

type PreferencesConfig =
  | { layout: 'center' }
  | { layout: 'sidebar'; side?: 'left' | 'right' }
  | { layout: 'pushDown'; edge?: 'top' | 'bottom' };

Shared fields: title, description, acceptLabel, rejectLabel, savePreferencesLabel, showCookieList, googlePrivacyLink, plus column labels for the cookie table.

Script blocking

interface ScriptBlockingRule {
  pattern: string;
  category: string;
}

Scripts whose src contains pattern are held until the user consents to the matching category. Patterns are plain substring matches — no regex.

scriptBlocking: [
  { pattern: 'google-analytics.com', category: 'analytics' },
  { pattern: 'connect.facebook.net', category: 'advertisement' },
],

Integrations

interface IntegrationsConfig {
  gcm?: { enabled: boolean };       // Google Consent Mode v2
  shopify?: { enabled: boolean };   // Shopify Customer Privacy
}

Implementations live in @cookiepal-oss/integrations.

Backend logging

Set backendURL to a self-hosted capture server. Every accept / reject / customise event POSTs { consentId, consent } to <backendURL>/consent. The server stamps IP, User-Agent, timestamp, and edge-provided country / region.

i18n

interface I18n {
  defaultLocale: string;
  locales: Record<string, I18nMessages>;
}

Built-in translations ship for 25 locales with per-key fallback. Any key you set in locales[lang] wins; unset keys fall back to the built-in bundle, then to defaultLocale.

Configuration

On this page