@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