Devtools

Documentation: CookieChimp Consent SDK. A floating development panel for CookieChimp. It shows:

consent state: consent id, last action, whether a decision is still needed, and each category
region, regulation, GPC and language
scripts, iframes and requests blocked by gateScripts, blockDynamic and blockNetwork
the connected-mode sync queue, when a sync client is passed
the config source (local or dashboard)

It can also simulate a region and the GPC signal.

import { createConsent } from "@cookiechimp/core";
import { gateScripts } from "@cookiechimp/core/gate";
import { mountDevtools } from "@cookiechimp/devtools";
import { readSimulation } from "@cookiechimp/devtools/simulation";

const consent = createConsent({ ...config, ...readSimulation() });
const gate = gateScripts(consent);
const devtools = mountDevtools({ consent, blockers: [gate] });

Options

Option	Default	Purpose
`consent`	required	A consent runtime (anything with `get` and `subscribe`).
`blockers`	`[]`	Controllers with `blocked()`: gate, dynamic and network blockers.
`sync`	none	A sync client with `queue()`. Without it the panel shows “Not connected (local mode)”.
`configSource`	`"local"`	`"local"` or `"dashboard"`.
`open`	`false`	Start with the panel open.
`refreshMs`	`1000`	Refresh the lists while open; `0` turns the timer off. The panel also refreshes on every consent change.
`nonce`	none	Nonce for the panel’s style element under a strict CSP.
`reload`	`location.reload()`	Called after a simulation is saved or cleared.
`allowProduction`	`false`	The panel does not mount in a production build unless this is set. Script-tag and CDN builds without `process` count as production.

mountDevtools returns { element, refresh, open, close, unmount }.

Simulating a region and GPC

The core runtime fixes its region and GPC when it is created, so a simulation applies on the next load. The panel saves a simulated country (2 letters), optional region (up to 3 letters or digits) and GPC flag to sessionStorage, previews the regulation that would apply, and reloads the page. Spread readSimulation() from the small @cookiechimp/devtools/simulation subpath into your config to apply it. “Clear simulation” removes it and reloads. readSimulation only reads storage when the build is known to be in development (process is defined and process.env.NODE_ENV !== "production"). Production builds, and script-tag, CDN or other builds where process is not defined, are treated as production: it returns null without reading storage, even when valid data is stored, so a visitor cannot edit cc_devtools_simulation in sessionStorage to drop GDPR or turn off GPC. To read it in a production build, for example on a staging site, call readSimulation({ allowProduction: true }). Only do that where visitors cannot reach the build. In every mode it validates stored data strictly and returns null for anything malformed, so a tampered value is ignored, not thrown. Pass { storage } to read from another storage.

Safety

The panel never makes a network request, and it inserts no scripts, iframes, images or links.
Every value, including blocked URLs, category names and queued records, is written as text, never parsed as markup. The panel lives in a shadow root, so page styles do not leak in or out.
Invalid options throw in development and warn in production (where the panel stays unmounted). Every guard fails closed: a build without process is treated as production.
Escape closes the panel while focus is inside it, and returns focus to the toggle button.

Get started

SDK reference

Options

Simulating a region and GPC

Safety

​Options

​Simulating a region and GPC

​Safety

Options

Simulating a region and GPC

Safety