@growth-labs/consent

Geography-aware consent management. Banner UI, cookie gating, and a utility other packages use to check consent state. Generic — not analytics-specific.

Config

import consent from '@growth-labs/consent'

consent({
  mode: 'geography',                             // 'required' | 'geography' | 'disabled'
  consentCookieName: 'gl_consent',
  autoInject: true, // default: package injects the banner script on every page
  purposes: {
    analytics: { label: 'Analytics', description: 'Helps us understand...', required: false },
    marketing: { label: 'Marketing', description: 'Personalized content...', required: false },
  },
  // requireConsentRegions defaults to EU/EEA + UK + Brazil
})

What It Injects

Middleware: Reads gl_consent cookie → populates context.locals.consent with { analytics: boolean, marketing: boolean, required: boolean }.

Banner: Auto-injected by the integration by default. It shows when consent is required and no cookie exists, supports Accept all / Decline / Manage toggles, and listens for gl:consent_reopen.

Set autoInject: false only when a site intentionally renders the package component itself. The manual component must receive the same runtime values the injected banner uses:

---
import ConsentBanner from '@growth-labs/consent/components/ConsentBanner.astro'

const purposes = [
  { key: 'analytics', label: 'Analytics', description: 'Helps us understand traffic' },
  { key: 'marketing', label: 'Marketing', description: 'Personalized content' },
]
---

<ConsentBanner
  consentRequired={Astro.locals.consent?.required ?? false}
  cookieName="gl_consent"
  purposes={purposes}
  position="bottom"
  showManageLink={true}
/>

Programmatic Reopen

For footer links or privacy pages that should reopen the in-page banner instead of sending users to a separate route:

document.dispatchEvent(
  new CustomEvent('gl:consent_reopen', {
    detail: { view: 'preferences' }, // or 'main'
  }),
)

The banner reuses any existing consent cookie to prefill the checkboxes before it opens.

How Geography Detection Works

Uses CF-IPCountry header (available on all Cloudflare Workers requests). If visitor's country is in requireConsentRegions list → consent required. US visitors → consent not required (mode: geography).

Checking Consent in Other Packages

import { isConsentGranted } from '@growth-labs/consent/utils'

if (isConsentGranted(context, 'analytics')) {
  // Set tracking cookies, fire analytics
}

If @growth-labs/consent is NOT installed, isConsentGranted() always returns true (appropriate for US-only sites).

Integration Order

Consent middleware runs AFTER auth, BEFORE analytics. List order in astro.config.mjs: auth → consent → analytics.

Key Patterns

• Virtual module: virtual:growth-labs/consent/config
• Runtime state self-seeds from the virtual config in middleware, routes, and utils
• Cookie gl_consent stores analytics:true,marketing:false
• Banner is minimal HTML — consumers style with CSS/Tailwind
• Client-side control uses gl:* CustomEvent events on document, including gl:consent_reopen
• Zaraz Consent Mode gates GA4 + third-party scripts