@opencookies/scripts

Pre-built defineScript integrations for the most common third-party vendors. Each integration is a thin factory that returns a ScriptDefinition matching the vendor's documented snippet, with sensible defaults for the consent category and pre-consent call queueing — so you can drop them straight into gateScript without writing the snippet by hand.

Each integration is its own subpath export, so only the ones you import end up in your bundle.

Install#

npm install @opencookies/core @opencookies/scripts

Usage#

import { gateScript } from "@opencookies/core";
import { metaPixel } from "@opencookies/scripts/meta-pixel";

const pixel = metaPixel({ pixelId: "1234567890" });
const dispose = gateScript(store, pixel);

The factory returns a plain ScriptDefinition. gateScript installs a stub at every queued global before consent, replays the calls into the real client once the script loads, and removes itself when you call the dispose function.

You can also import everything from the package root if tree-shaking the entry barrel is fine for your build:

import { ga4, metaPixel, posthog } from "@opencookies/scripts";

Integrations#

Every factory accepts a requires (override the default ConsentExpr) and id (override the default script id) on top of the per-vendor options below.

Google Analytics 4 — @opencookies/scripts/ga4#

import { ga4 } from "@opencookies/scripts/ga4";

ga4({ measurementId: "G-XXXXXXX", config: { send_page_view: false } });

Defaults: requires: "analytics", queues dataLayer.push and gtag.

Meta Pixel — @opencookies/scripts/meta-pixel#

import { metaPixel } from "@opencookies/scripts/meta-pixel";

metaPixel({ pixelId: "1234567890" });

Defaults: requires: "marketing", queues fbq. Fires fbq("init", pixelId) and fbq("track", "PageView") on load.

PostHog — @opencookies/scripts/posthog#

import { posthog } from "@opencookies/scripts/posthog";

posthog({ apiKey: "phc_xxx", apiHost: "https://eu.i.posthog.com" });

Defaults: requires: "analytics", apiHost: "https://us.i.posthog.com", queues the common posthog.* methods. Calls posthog.init(apiKey, { api_host, ...options }) on load.

Segment — @opencookies/scripts/segment#

import { segment } from "@opencookies/scripts/segment";

segment({ writeKey: "WRITE_KEY" });

Defaults: requires: "analytics", queues the common analytics.* methods. Calls analytics.page() on load.

Google Tag Manager — @opencookies/scripts/google-tag-manager#

import { googleTagManager } from "@opencookies/scripts/google-tag-manager";

googleTagManager({ containerId: "GTM-XXXXXX" });

Defaults: requires: "marketing", queues dataLayer.push. Seeds dataLayer with gtm.start on load.

Hotjar — @opencookies/scripts/hotjar#

import { hotjar } from "@opencookies/scripts/hotjar";

hotjar({ siteId: 1234567 });

Defaults: requires: "analytics", version: 6, queues hj. Sets _hjSettings on load.

Adding a new integration#

PRs welcome. To add a vendor:

1. Add src/<vendor>.ts exporting a factory that returns defineScript({ id, requires, src, queue, init }). Mirror the vendor's documented snippet — init should match what their inline bootstrap does, and queue should list every global a developer might call before consent.
2. Add src/<vendor>.test.ts asserting the snippet shape and an end-to-end gateScript flow (use the helpers in src/test-helpers.ts).
3. Register the entry in vite.config.ts and the matching ./<vendor> subpath in package.json exports.
4. Add a section to this README with the install snippet and defaults.

License#

Apache-2.0