@consentx/nuxt

v1.0.2

Published

16 days ago

ConsentX cookie consent & CMP for Nuxt 3 — GDPR, CCPA, DPDPA. Injects the ConsentX embed via your Site Key, with Google Consent Mode v2 defaults and a consent event hook.

0High
0Medium
0Low

intelligencex

nuxt nuxt-module consentx cookie-consent cmp gdpr ccpa dpdpa consent-mode privacy

@consentx/nuxt is a Nuxt 3 module that installs the ConsentX cookie-consent banner with a single Site Key. It injects the self-contained ConsentX embed as an ES module (after hydration, so it is SPA-safe), seeds Google Consent Mode v2 denied-by-default defaults, and gives you a typed event hook for the visitor's consent choice.

The ConsentX server side is already live on https://app.consentx.io — the module is purely the client. There is no redirect handshake: you paste your Site Key (Model C). Add your domain to the site's allowlist in the ConsentX dashboard, and the banner loads.

Features

Site-key install — one value, set in config or via an env var per environment. No build-time secret, no server round-trip.
SPA-safe embed — the embed.js module is injected after app:mounted so Nuxt's DOM reconciliation never strips the #consentx-cookie-consent div.
Google Consent Mode v2 — denied-by-default stub printed at the very top of <head> before any analytics tag (toggleable).
Consent event — listen for cx:consent (detail.granted = array of granted category slugs). window.ConsentX.open() opens the preferences UI.
Overridable host — point at staging / self-hosted ConsentX with appUrl.
Typed — runtimeConfig.public.consentx is fully typed.

Install

# npm
npm install @consentx/nuxt

# pnpm
pnpm add @consentx/nuxt

# yarn
yarn add @consentx/nuxt

Add the module to your nuxt.config:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@consentx/nuxt'],

  consentx: {
    // Paste your Site Key from the ConsentX dashboard
    // (Websites -> your site -> Site Key).
    siteKey: 'YOUR_SITE_KEY',
  },
})

That's it. Run nuxt dev, load any page, and the ConsentX banner appears.

Prefer an environment variable?

Leave siteKey out of nuxt.config and provide it at boot — handy for staging vs production keys without rebuilding:

NUXT_PUBLIC_CONSENTX_SITE_KEY=YOUR_SITE_KEY nuxt build

Configuration

All options live under the consentx key in nuxt.config:

export default defineNuxtConfig({
  modules: ['@consentx/nuxt'],

  consentx: {
    siteKey: 'YOUR_SITE_KEY',          // required (here or via env)
    appUrl: 'https://app.consentx.io', // override for staging / self-hosted
    consentMode: true,                 // Google Consent Mode v2 defaults
    enabled: true,                     // master switch
  },
})

| Option | Type | Default | Description | | ------------- | --------- | --------------------------- | --------------------------------------------------------------------------- | | siteKey | string | '' | Your ConsentX Site Key. Falls back to NUXT_PUBLIC_CONSENTX_SITE_KEY. | | appUrl | string | https://app.consentx.io | ConsentX app host (scheme + host, no trailing slash). | | consentMode | boolean | true | Inject the Consent Mode v2 denied-by-default stub before any analytics tag. | | enabled | boolean | true | Set false to keep the module installed but inert (e.g. previews). |

These map to runtimeConfig.public.consentx, so you can also override the host or consent-mode flag per environment:

NUXT_PUBLIC_CONSENTX_SITE_KEY=YOUR_SITE_KEY
NUXT_PUBLIC_CONSENTX_APP_URL=https://staging.consentx.io

What gets injected

Into <head> (when consentMode is on, denied-by-default, before any tag):

<script>
window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}
gtag('consent','default',{ad_storage:'denied',analytics_storage:'denied',
ad_user_data:'denied',ad_personalization:'denied',functionality_storage:'denied',
personalization_storage:'denied',security_storage:'granted',wait_for_update:500});
</script>

After hydration, the embed (carrying your key via window.consentx_key):

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

embed.js is self-contained: it injects the scoped widget CSS + JS, renders the banner into a #consentx-cookie-consent div it appends to document.body, reads geo/config from the server, and emits cx:consent. The ConsentX widget emits the matching gtag('consent','update', …) calls on the visitor's choice.

Reacting to consent

Listen for the cx:consent event anywhere on the client (a component, a plugin, or app-level):

<script setup lang="ts">
onMounted(() => {
  window.addEventListener('cx:consent', (e: Event) => {
    const granted = (e as CustomEvent<{ granted: string[] }>).detail.granted
    // granted is an array of granted category slugs, e.g. ['analytics', 'marketing']
    if (granted.includes('analytics')) {
      // load your analytics SDK now
    }
  })
})

function openPreferences() {
  // exposed by the widget once loaded
  window.ConsentX?.open()
}
</script>

Develop / build the module

npm install
npm run dev:prepare   # generate the type stubs
npm run build         # build into dist/ via @nuxt/module-builder
npm run test          # vitest

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme