The CookieYes SDK is seven open-source, MIT-licensed npm packages that add cookie consent to React and Next.js apps without a third-party script. It renders on the server, makes zero network calls by default, blocks trackers until your visitor consents, and keeps consent records in the browser or on your own server. It is the same cookie consent solution behind CookieYes on 1.5M+ websites, now installable from npm.
Key takeaways
- Seven MIT-licensed npm packages for cookie consent in React and Next.js, with no third-party script.
- Cookie-only mode makes zero network calls; self-hosted mode keeps records on your own infrastructure.
- Blocking works in three layers, with documented limits.
- Free on unlimited domains; the platform adds stored records, scanning, reporting and 20+ regulations.
One command
npx @cookieyes/cli init
The CLI detects your framework, asks four questions, writes the code, and refuses to overwrite existing work. No telemetry. If you would rather wire it up by hand, it is one client component mounted in your root layout, which stays a Server Component. The README has the snippet.
Compatibility is verified in CI against Next.js 14, 15 and 16 with React 18 and 19, and the same component covers both the App Router and the Pages Router.
Why this exists
Pasting a script tag still works well on WordPress, Shopify and Wix, and it is why so many websites run CookieYes today. But there are teams who will not ship opaque third-party code inside their product.
Those teams want from consent what they expect of any other dependency: readable source, a typed config, testable behaviour, and control over where the data goes. That is what the SDK is.
Your consent data stays yours
Two storage modes ship today, and neither puts the records in our hands.
- Cookie-only mode keeps the visitor's choice in a cookie in their own browser. The SDK makes no outbound requests at all, so there is no third-party call and nothing phoning home.
- Self-hosted mode posts consent records to an endpoint you control, or to a custom
persist() adapter. Data-residency and no-egress requirements get answered in your own infrastructure, without a sales call.
Both modes are free and unlimited, and neither needs a CookieYes account or key.
Blocking that holds
Consent tooling is only as good as its enforcement, so blocking works in three independent layers.
- Consent-gated injection. Scripts and iframes are never added to the page until the visitor grants the category, through gated components or a vendor preset.
- Network blocking (opt-in). Patches
fetch, XMLHttpRequest and sendBeacon against your rules. It is a safety net for code you do not control, not a security boundary, and it will not stop a <script src> element. - Stop handlers on revoke. When consent is withdrawn, the SDK calls each vendor's own stop-tracking API so loaded tags go quiet.
Presets ship for Google Tag Manager, GA4, Google Ads, Meta Pixel, Segment and custom scripts. We document which revoke cleanly and which need a reload, and the SDK shows a dismissible notice rather than reloading someone's page on its own. Google's own consent mode guidance explains the default state you still own.
Built the way you build
| What you get | Detail |
|---|
| Google Consent Mode v2 | All seven signals on load and on every change, deny-by-default included |
| SSR without flicker | A returning visitor's stored choice is read on the server, so the banner is never in their HTML |
| Full design control | Theme tokens for colour, radius, font and position, or go fully headless |
| Strict CSP support | No inline styles, so it runs under a strict Content Security Policy with no nonce |
| Type-safe config | 100% TypeScript, so an invalid setup fails at compile time |
| A real test harness | `@cookieyes/test` runs the engine with no DOM or network, so consent logic is unit-testable |
| Regional behaviour | GDPR opt-in, CCPA opt-out, GPC honoured by default, fail-safe fallback to the strictest regime |
| Five languages | English, Spanish, French, German, Italian, lazily loaded, with live switching and RTL |
| Signed releases | Built on GitHub Actions with npm build provenance, traceable to the source commit |
Accessibility is in there too: keyboard operation, focus trapping and restore, visible focus rings, reduced-motion support, ARIA labelling, and automated checks in CI.
The seven packages
@cookieyes/core — headless engine, zero runtime dependencies@cookieyes/react — components, 13 SSR-safe hooks, headless primitives@cookieyes/nextjs — App and Pages Router, plus server-only exports@cookieyes/cli — interactive scaffolder@cookieyes/scripts — consent-gated vendor presets@cookieyes/translations — locale catalogue@cookieyes/test — test double for consent logic
What is free, and what we sell
The SDK is MIT-licensed and free on unlimited domains, with no pageview cap. The only commercial hook is the "Powered by CookieYes" banner attribution, which paid plans remove.
The platform is where the compliance evidence lives: consent logs, automatic cookie scanning, consent analytics, 20+ regulations, 30+ banner languages and IAB TCF v2.3, behind a Google-certified CMP with ISO 27001 and SOC 2 Type II. Full detail sits on the features and pricing pages.
That split is deliberate. The SDK gives you the banner and the blocking. The platform gives you the evidence and the oversight.
What comes next
Hosted storage is next on the roadmap, with IAB TCF, our geo-detection service and cookie scanning alongside it.
Geo-targeting already works today when you supply the region, and a built-in helper reads the geo headers Vercel and Cloudflare already add. What comes next is our own country-lookup service, so you do not have to wire that part up at all. We will publish dates when they are firm.
Source, docs and issues live in the CookieYes SDK repository on GitHub, and [email protected] reaches a human. For the script-tag install, see the CookieYes documentation.
FAQ
