@palmetto/cookie-consent

Shared CookieYes consent integration for Palmetto frontends and backends. One versioned package so each repo stops re-implementing the same consent glue.

The cookie banner itself is rendered by CookieYes's own CDN script — this package ships the logic around it (reading consent, subscribing to changes, gating Segment, parsing the consent cookie server-side), not any UI.

Installation

yarn add @palmetto/cookie-consent

Peer dependencies are installed only for the subpaths you use:

• ./react → react (>=18)
• ./segment → @segment/analytics-consent-tools (>=1)
• . and ./server → no peers

Entry points

| Import | Use in | Contents | | ---------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @palmetto/cookie-consent | any browser code | getCkyConsent, onCkyConsentUpdate, DEFAULT_CONSENT_CATEGORIES, activeLawToConsentModel, injectCookieYesScript, the shared types, and the ambient window.getCkyConsent typing | | @palmetto/cookie-consent/react | React apps | useCkyConsent(), <CookieConsentProvider> | | @palmetto/cookie-consent/segment | apps loading Segment | withCookieYes(), CookieYesSettings | | @palmetto/cookie-consent/server | Node/Nest | parseConsentCookie(), KNOWN_CONSENT_CATEGORIES, DEFAULT_CONSENT | | @palmetto/cookie-consent/testing | tests / local dev | setMockConsent(), clearMockConsent() — simulate consent without CookieYes (needs a DOM) |

The subpaths keep react out of backends and @segment/* out of consumers that gate their own analytics — importing /server never pulls a browser or React module into the require graph.

Getting started

Loading the CookieYes script

The zone ID and feature gate stay per-app env — this package does not ship a ready-made loader component.

Vite (client-only):

import { injectCookieYesScript } from "@palmetto/cookie-consent";

useEffect(() => {
  injectCookieYesScript(import.meta.env.VITE_COOKIEYES_ZONE_ID);
}, []);

Next.js: keep next/script with strategy="beforeInteractive" for SSR ordering — do not use injectCookieYesScript.

Reading consent in React

import { useCkyConsent } from "@palmetto/cookie-consent/react";

function Analytics() {
  const { categories } = useCkyConsent();
  if (!categories.analytics) return null;
  // ...
}

Gating Segment

import { withCookieYes } from "@palmetto/cookie-consent/segment";

export const analytics = withCookieYes(new AnalyticsBrowser());

Server (Nest middleware)

import { parseConsentCookie } from "@palmetto/cookie-consent/server";

const consent = parseConsentCookie(req.cookies["cookieyes-consent"]);

Local development & testing

CookieYes does not load on localhost — its zones are domain-restricted, so no banner appears and window.getCkyConsent is never installed. You have two ways to work around this:

1. Mock consent (unit tests, local UI work) — drive consent-gated code directly, no CookieYes required:

   import {
     setMockConsent,
     clearMockConsent,
   } from "@palmetto/cookie-consent/testing";
   
   // simulate a visitor who accepted analytics
   setMockConsent({
     categories: { analytics: true },
     isUserActionCompleted: true,
   });
   // ...assert your gated behavior...
   clearMockConsent(); // in teardown

   Under the hood this installs window.getCkyConsent and dispatches the cookieyes_consent_update event — the same thing the real CDN script does. Needs a DOM (jsdom in tests, or a real browser console for manual poking).

2. Real banner against localhost — register a staging URL (or a tunnel URL from ngrok/cloudflared) as the site URL in a CookieYes zone, then run the app behind that URL. CookieYes lets you switch the zone's URL later, so you can start with staging and repoint to production.

Notes for consumers

• The data-cookieyes="..." pixel category slugs stay per-app config — they must match the slugs configured in each app's CookieYes dashboard zone.
• activeLaw values and the exact CkyConsent shape mirror what CookieYes emits; treat this package's types as the single source of truth across repos.