@consentx/gatsby

v1.0.2

Published

15 days ago

Cookie consent & CMP for Gatsby — GDPR, CCPA, DPDPA. Injects the ConsentX embed (banner, Google Consent Mode v2, pre-consent tracker blocking) and exposes a useConsentX consent hook.

0High
0Medium
0Low

intelligencex

gatsby gatsby-plugin consentx cookie-consent consent cmp gdpr ccpa dpdpa consent-mode privacy

How it works

This is Model C (site-key): there is no redirect handshake. You paste your Site Key (from the ConsentX dashboard → Websites → your site → Copy Site Key) into gatsby-config.js. At build/SSR time the plugin's onRenderBody injects a single self-contained module into <head>:

<script type="module" src="https://app.consentx.io/api/SITE_KEY/embed.js"></script>

embed.js injects the scoped widget CSS + JS, mounts the banner into a #consentx-cookie-consent div it appends to the body, reads geo/config from the ConsentX server, emits the cx:consent event (detail.granted = array of granted category slugs), and exposes window.ConsentX (open preferences).

Make sure your site's domain is on the allowlist for that Site Key in the ConsentX dashboard (the "Add website" flow handles this). The embed only loads for allowlisted domains.

Install

npm install @consentx/gatsby
# or
yarn add @consentx/gatsby
# or
pnpm add @consentx/gatsby

Usage

Add the plugin to gatsby-config.js and set your Site Key:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "@consentx/gatsby",
      options: {
        // Required: copy from ConsentX dashboard -> Websites -> your site.
        siteKey: process.env.CONSENTX_SITE_KEY,
      },
    },
  ],
};

That is the whole integration. Run gatsby build (or gatsby develop) and the banner appears on every page.

Options

| Option | Type | Default | Description | | ------------- | --------- | --------------------------- | -------------------------------------------------------------------------------------------- | | siteKey | string | — (required) | Your ConsentX Site Key. | | appHost | string | https://app.consentx.io | ConsentX app host (scheme, no trailing slash). Override for staging / self-hosted. | | consentMode | boolean | true | Inject the Google Consent Mode v2 denied-by-default stub before analytics tags. |

{
  resolve: "@consentx/gatsby",
  options: {
    siteKey: process.env.CONSENTX_SITE_KEY,
    appHost: "https://app.consentx.io",
    consentMode: true,
  },
}

Reacting to consent in your components

Use the useConsentX hook to gate client-side third-party code (maps, video embeds, chat widgets) on the visitor's actual choice. It subscribes to the widget's cx:consent event and updates live when the visitor changes their mind.

import React from "react";
import { useConsentX } from "@consentx/gatsby/use-consentx";

export default function MapEmbed() {
  const { ready, hasConsent, openPreferences } = useConsentX();

  if (!ready) return null; // wait for a decision

  if (!hasConsent("marketing")) {
    return (
      <button onClick={openPreferences}>
        Enable marketing cookies to load the map
      </button>
    );
  }

  return <iframe title="map" src="https://maps.example.com/embed" />;
}

The hook returns:

| Field | Type | Description | | ----------------- | ----------------------------- | ------------------------------------------------- | | ready | boolean | true once a consent decision has been observed. | | granted | string[] | Granted category slugs, e.g. ["analytics"]. | | hasConsent | (category: string) => boolean | Test a single category. | | openPreferences | () => void | Open the ConsentX preferences UI. |

TypeScript users: types ship with the package, including a cx:consent WindowEventMap augmentation and a window.ConsentX declaration.

Google Consent Mode v2

With consentMode: true (default) the plugin prints the denied-by-default gtag('consent','default',…) stub before the embed, so analytics/ads are denied until the visitor chooses. The ConsentX widget then emits the matching gtag('consent','update',…) calls on their decision. Set consentMode: false if you manage Consent Mode defaults yourself.

Local check / build

The plugin ships plain CommonJS that Gatsby loads directly, so there is no transpile step. npm run build runs a self-contained verification of the embed contract (URL building, option validation, and the SSR head injection):

npm run build

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme