Runtime and server helpers
Direct access to the runtime from plain code, and reading a returning visitor's consent on the server.
What this page covers
Two things the regular hooks do not do: reaching the runtime from code that is not a component, and reading a visitor's saved consent on the server so the banner is right on the first paint. Most apps need neither. If you want to read or change consent in a component, use useConsent() and useConsentActions().
Module-level registry
initCookieYes() registers one runtime for the page. getCookieYes() returns it from any code, and useConsentRuntime() returns the same object inside a component.
import { getCookieYes } from "@cookieyes/nextjs";
export function logCurrentConsent() {
const snapshot = getCookieYes().getSnapshot();
console.log(snapshot.committedCategories);
}The runtime gives you getSnapshot(), subscribe(listener), manager (every action) and getIntegrations() for a debug panel.
Both throw if no runtime is registered yet, with [cookieyes] No runtime is registered. Every other hook returns a safe default instead. So call them only from code that runs in the browser after initCookieYes(), never during server rendering.
resetCookieYes() clears the registry. Use it between tests.
Read a returning visitor's consent on the server
By default the server does not know what a visitor chose, so it renders the banner for everyone and the browser removes it after loading, which a returning visitor sees as a flash. To avoid it, read the saved decision from the request cookie and pass it to CookieYesProvider.
import { CookieYesProvider } from "@cookieyes/nextjs";
import { getServerConsent } from "@cookieyes/nextjs/server";
// Your consent manager from Installation.
declare function CookieYesRoot(): React.ReactElement;
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const initialConsent = await getServerConsent({ regulation: "GDPR" });
return (
<html lang="en">
<body>
<CookieYesProvider regulation="GDPR" initialConsent={initialConsent}>
<CookieYesRoot />
{children}
</CookieYesProvider>
</body>
</html>
);
}getServerConsent() reads the cookie for you and returns the saved decision, or null for a visitor who has not chosen yet. Reading cookies makes the route dynamic, as any cookies() call does.
Pass the result to the provider only. Never write a visitor's consent into initCookieYes() or onto the runtime: the server runs one process for every visitor at once, and per-visitor values there would leak between them.
To choose the regulation per visitor on the server, regionFromHeaders(headers) from @cookieyes/core reads the visitor's region, such as "DE" or "US-CA", from the hosting provider's headers. Map it to "GDPR" or "CCPA" and pass that as the provider's regulation. See the region option on Configuration.
Common mistakes
[cookieyes] No runtime is registered during server rendering.
useConsentRuntime() or getCookieYes() ran on the server. Use useConsent() there, or move the call into a browser-only code path.
The banner flashes on every load for a returning visitor.
No initialConsent reached CookieYesProvider. Read it on the server as shown above.
One visitor's consent appears for another in production.
A per-visitor value was written into initCookieYes() or onto the runtime on the server. Per-visitor values go on CookieYesProvider only.
Next steps
- Part and state contract: the selectors that are stable for CSS and tests
- useConsent: read consent in a component