CookieYes Consent SDK

Open-source, developer-first cookie consent SDK. The same compliance engine that powers CookieYes for 1.5M+ websites — now installable via npm.

Packages

Package	Description	Version
`@cookieyes/core`	Headless consent engine — zero UI, zero deps
`@cookieyes/react`	React adapter — components and hooks
`@cookieyes/scripts`	Ready-made, consent-gated third-party integrations (Segment, custom scripts, …)
`@cookieyes/nextjs`	Next.js App Router adapter
`@cookieyes/translations`	Curated, per-locale translation catalog
`@cookieyes/cli`	Scaffolder — wire the SDK into an existing app
`@cookieyes/test`	Headless test double (+ `/react`) — unit-test consent code with no browser

Architecture

@cookieyes/nextjs
    └── @cookieyes/react
            └── @cookieyes/core   (zero deps)

All business logic lives in @cookieyes/core. Framework adapters are thin wrappers — no logic, only wiring.

Not sure which API reads consent status in your case? See the decision tree — there's one recommended path per platform; everything else is a documented low-level option for a specific edge case.

Compatibility

Next.js	React	React DOM	Verified	Build + typecheck	SSR (HTML + cookie value)	Behaviour (jsdom)
14.0.0 (declared floor)	18.0.0 (declared floor)	18.0.0	2026-08-27	pass	pass	pass
15.5.24	18.3.1	18.3.1	2026-08-27	pass	pass	pass
16.3.0	19.2.8	19.2.8	2026-08-27	pass	pass	pass

Verified by installing the exact versions above, building a real Next.js app, server-rendering it and asserting the banner's HTML (and a returning visitor's cookie value) is correct, then running behaviour assertions in jsdom via @cookieyes/test. Node 20, pnpm. See rationale for why this stops short of a real browser.

Not verified by this table:

Any Next.js/React version outside the rows above.
npm/yarn as the install client.
No real browser paint or hydration — SSR is asserted via server-rendered HTML/fetch only; client behaviour is asserted in jsdom, not a browser DOM (no Playwright).
Node, package-manager and module-resolution dimensions are not yet varied — every combination above ran on Node 20 / pnpm / moduleResolution=bundler.

Quick start

You configure the SDK once with a single config object, then drop in the banner and dialog components. Every package — core, React, and Next.js — accepts the exact same initCookieYes(config) shape. Full options are documented in Configuration.

React

npm install @cookieyes/react

// components/consent-manager.tsx
"use client";

import {
  CookieBanner,
  CookiePreferences,
  RecallButton,
  initCookieYes,
} from "@cookieyes/react";

initCookieYes({
  mode: "cookie-only",    // "cookie-only" | "self-hosted"
  regulation: "GDPR",     // "GDPR" | "CCPA" | "DEFAULT"
  colorScheme: "system",  // "light" | "dark" | "system"
});

export function CookieYesRoot() {
  return (
    <>
      <CookieBanner />
      <CookiePreferences />
      <RecallButton />
    </>
  );
}

Render <CookieYesRoot /> once near the root of your app.

Next.js App Router

npm install @cookieyes/nextjs

Create the same "use client" consent-manager component (import from @cookieyes/nextjs instead), then mount it in your root layout:

// app/layout.tsx
import { CookieYesRoot } from "@/components/consent-manager";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <CookieYesRoot />
      </body>
    </html>
  );
}

Scaffold into an existing project

The CLI detects your framework and package manager, installs the right adapter, and generates the consent-manager component for you:

npx @cookieyes/cli init

Repository layout

sdk/
  core/          @cookieyes/core         headless engine
  react/         @cookieyes/react        React components + hooks
  scripts/       @cookieyes/scripts      consent-gated third-party integrations
  nextjs/        @cookieyes/nextjs       Next.js App Router adapter
  translations/  @cookieyes/translations per-locale catalog
  cli/           @cookieyes/cli          scaffolder
  test/          @cookieyes/test         headless test double (+ /react)

Local development

Prerequisites: Node.js ≥ 20, pnpm ≥ 10

git clone https://github.com/cookieyes/cookieyes.git
cd cookieyes
pnpm install
pnpm build       # build all packages (Turborepo)
pnpm test        # run the test suites (Vitest)
pnpm typecheck   # TypeScript across all packages
pnpm lint        # Biome lint + format check
pnpm dev         # watch mode for all packages

Contributing

We welcome contributions! Please read CONTRIBUTING.md and our Code of Conduct before opening a pull request. Releases are automated with Changesets — run pnpm changeset to describe your change.

Security

To report a vulnerability, see SECURITY.md. Please do not open public issues for security reports.

@cookieyes/scripts
Release 0.2.1

Release 0.2.1

0.2.1

0.2.0

0.1.1

0.1.0

0.0.0

Documentation

CookieYes Consent SDK

Packages

Architecture

Compatibility

Quick start

React

Next.js App Router

Scaffold into an existing project

Repository layout

Local development

Contributing

Security

License

Stats

Releases

Contributors

@cookieyes/scripts Release 0.2.1

Release 0.2.1 Toggle Dropdown 0.2.1 0.2.0 0.1.1 0.1.0 0.0.0

Documentation

CookieYes Consent SDK

Packages

Architecture

Compatibility

Quick start

React

Next.js App Router

Scaffold into an existing project

Repository layout

Local development

Contributing

Security

License

Stats

Releases

Contributors

@cookieyes/scripts
Release 0.2.1

Release 0.2.1

0.2.1

0.2.0

0.1.1

0.1.0

0.0.0