@revenexx/consent-manager-nuxt

Why

• 🖥️ Rendered by your own server. No consent SaaS script is loaded before the decision. The Nuxt server reads the rvx_consent cookie and the published policy, so the first response already contains the banner if one is needed, and nothing the visitor has not allowed. You get no layout shift and no flash of tracking.
• ⚖️ "Reject all" sits next to "Accept all". Both buttons are on the first layer, in every layout (box, bar, modal), and share one CSS class, so you cannot style one of them down. This is deliberately not configurable.
• 📊 Google Consent Mode v2 (basic). The default command (everything denied except security_storage) is the first dataLayer entry in <head>, and each decision pushes an update.
• 🧱 <ConsentGate> for embeds. YouTube, maps and similar embeds are not rendered at all until their vendor is allowed. A local placeholder takes their place, with Load once for a single vendor.
• 🔌 One seam for loaders. $consentProvider plugs straight into @nuxt/scripts triggers, and @revenexx/tag-manager-nuxt uses the same seam.
• 🧾 Decisions are recorded without personal data. Each decision is stored against the exact policy version that was shown. The record carries no IP address, no full user agent and no query string.
• 🛡️ Fails closed. If there is no policy, no credentials or the gateway is down, no banner is shown and nothing optional loads.
• 🎨 Themeable or headless. CSS variables, a slot for every surface, or useConsents() to build your own UI.

The consent configuration lives in the Consent Manager app (revenexx Experience Studio), not in nuxt.config: purposes and their legal bases, vendors, cookies and banner texts per locale. This module renders and enforces what that app publishes.

Contents

• Installation
• Quick start
• How it works
• Configuration
• Credentials and runtime config
• Components · <ConsentBanner> · <ConsentGate> · <ConsentPreferencesLink>
• useConsents()
• The consent provider
• Events and hooks
• Google Consent Mode v2
• Server routes
• Recipes
• TypeScript
• Compatibility
• Troubleshooting
• Related packages
• A note on legal bases
• Development and releasing

Installation

npm i @revenexx/consent-manager-nuxt @nuxt/scripts     # or pnpm add / yarn add

@nuxt/scripts is a peer dependency. The module installs it for you if it is missing from modules, but listing it yourself keeps the order explicit.

Quick start

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/scripts', '@revenexx/consent-manager-nuxt'],
  consentManager: {
    // every option has a default, see Configuration
  },
})

<!-- app.vue (or your layout) -->
<template>
  <NuxtPage />

  <!-- First layer and settings layer. Renders only when a decision is owed or the visitor reopens it. -->
  <ConsentBanner />

  <footer>
    <!-- Reopens the settings layer with the current decisions preset. -->
    <ConsentPreferencesLink />
  </footer>
</template>

Gate an embed:

<ConsentGate vendor="youtube" thumbnail="/media/video-preview.jpg">
  <iframe src="https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ" title="Video" allowfullscreen />
</ConsentGate>

Load a @nuxt/scripts script only once the visitor allows it:

const { $consentProvider } = useNuxtApp()

useScriptGoogleAnalytics({
  id: 'G-XXXXXXX',
  scriptOptions: { trigger: $consentProvider.trigger('google-analytics', 'statistics') },
})

google-analytics and statistics are codes from your published policy: a vendor code and one of that vendor's purpose codes.

For local development, point the module at a tenant (see Credentials):

# .env (never commit it)
NUXT_CONSENT_MANAGER_TENANT=<your-tenant>
NUXT_CONSENT_MANAGER_API_KEY=<your-gateway-api-key>

Without credentials the module still builds and renders. It shows no banner and allows nothing optional.

How it works

request ──► Nuxt server (plugin, SSR)
              │ reads cookie rvx_consent
              │ GET /_consent-manager/policy ──► api.revenexx.com
              │                                  /v1/consent-manager/delivery/policy
              │                                  (cached 60 s per tenant + market)
              ▼
            HTML: <head> Consent Mode default (+ update for a returning visitor)
                  <ConsentBanner> if a decision is owed
                  <ConsentGate> placeholders for vendors not allowed
              │
browser ──► visitor decides ──► cookie rvx_consent written
                              ├► gtag('consent','update', …)
                              ├► consent-manager:change hook + revenexx:consent DOM event
                              ├► @nuxt/scripts triggers resolve (scripts load, no reload)
                              └► POST /_consent-manager/record ──► /v1/consent-manager/records

When the banner shows. It shows when there is no valid rvx_consent cookie, when the cookie predates the latest material policy version, or when it is older than the policy's consent_lifetime_days (365 if unset). A malformed cookie counts as no cookie. When the policy is being previewed, the banner shows on every page load and closes after a decision on that page. The decision is not recorded.

What "allowed" means. allows(vendor, purpose) is false in an editor context, without a policy, for a vendor not in the policy and for a purpose that vendor does not serve. Otherwise it follows the effective legal basis (vendor.legal_basis_override ?? purpose.legal_basis):

What each button writes.

Revoking. A script cannot be unloaded. When a decision takes away a vendor that was allowed before, the module deletes that vendor's declared first-party cookies and local/session storage keys and then reloads the page (unless reloadOnRevoke: false).

Editor context. On theme-editor hosts and under the editor/preview paths, the module does not fetch the policy, renders no banner and no preferences link, and allows() is false for everything. Merchants editing a page never trigger a vendor.

The full normative description (cookie format, gating formula, failure modes) is in docs/contract.md.

Configuration

All options go under consentManager in nuxt.config.ts.

The layout (box / bar / modal), the consent lifetime, the exempt paths, whether the cookie table is shown and whether Consent Mode is on are policy settings in the Consent Manager app, not module options.

Credentials and runtime config

The two server routes call the revenexx gateway. They work out who they are calling as per request, in this order:

1. Brokered context (deployed revenexx Sites). The platform injects x-revenexx-tenant and a signed x-revenexx-context token into each request. The module forwards the token as Authorization: Bearer …. Nothing needs to be configured. If a request carries the tenant header but no token, a configured API key is used only if it belongs to that same tenant. A key is never sent on behalf of another tenant.
2. Tenant + API key (everywhere else). tenant and apiKey from runtime config are sent as x-revenexx-tenant + x-revenexx-api-key.

If neither is available, the policy route answers { policy: null, reason: 'not_configured' } and the module fails closed.

The options map to runtime config, so you can set them with environment variables at runtime:

Fallback. When a NUXT_CONSENT_MANAGER_* value is empty, the server routes fall back to the shop-wide NUXT_REVENEXX_API_URL, NUXT_REVENEXX_TENANT and NUXT_REVENEXX_API_KEY, then to https://api.revenexx.com for the URL.

Credentials are read at runtime only. Since 0.1.1 the module reads no environment variable while nuxt build runs, so a key present on the build machine never ends up in .output. (0.1.0 copied NUXT_REVENEXX_* into the server build as defaults — rebuild with 0.1.1 and rotate the key if you built with it set.) Writing apiKey or tenant into nuxt.config still bakes them into the build, so keep them in the environment.

The market is the incoming x-revenexx-market header if there is one. Otherwise it is the value of the marketCookie cookie, if it is a plain code of up to 32 characters (letters, digits, _, -). Otherwise no market is sent.

Components

All three components are registered globally. They read the state the plugin created, so they must be used inside the Nuxt app that installs the module.

<ConsentBanner>

The first layer and the settings layer. It renders only while a decision is owed or after the visitor reopened it. Place it once, for example in app.vue.

Banner API (slot props of first-layer, actions, preferences):

If you replace actions, keep Reject all next to Accept all. Accessibility: the banner is role="dialog", can be operated by keyboard and has visible focus. It is named by its heading through aria-labelledby; when a first-layer or preferences slot replaces that heading, the dialog carries the layer's title (title / preferences_title) as aria-label instead. Escape closes it once a decision exists. Only the modal layout traps focus. Focus returns to where it was after the decision. Styling and CSS variables: docs/theming.md.

<ConsentGate>

Blocks content until its vendor is allowed. Until then the default slot is not rendered at all: it is not merely hidden, and no request reaches the vendor. A placeholder takes its place.

The default placeholder shows the thumbnail, the notice and the Load once and Settings buttons. The buttons are hidden in editor context and when no policy is loaded.

<ConsentPreferencesLink>

A <button> that reopens the settings layer with the current decisions preset. Put it in the footer and on the privacy page. It is not rendered in editor context, nor while no policy is loaded (not configured, nothing published, gateway unreachable), since there is no choice to open.

useConsents()

Headless access for a theme that builds its own UI. Auto-imported. Call it in setup.

const consents = useConsents()

consents.decided.value                // has the visitor decided under the current policy?
consents.state.value                  // { purposes: { statistics: 'granted', … }, vendors: { youtube: 'granted' } }
consents.allows('youtube')            // any purpose of the vendor allowed?
consents.allows('google-analytics', 'statistics')
await consents.acceptAll()
await consents.save({ purposes: { statistics: 'granted', marketing: 'denied' } })
consents.open()                       // reopen the settings layer (as the privacy link does)

The locale is taken from @nuxtjs/i18n if it is installed, otherwise from Accept-Language (server) or navigator.language (client). The policy locale is matched exactly, then by language, then falls back to de, then to the first locale the policy has.

The consent provider

nuxtApp.$consentProvider is the only thing a script loader needs. It is the seam @revenexx/tag-manager-nuxt uses, and you can use it with @nuxt/scripts directly:

interface ConsentProvider {
  readonly ready: Promise<void>
  allows: (vendor: string, purpose: string) => boolean
  trigger: (vendor: string, purpose: string) => Promise<void> & { consented: Ref<boolean> }
  googleSignals: () => Record<GoogleSignal, 'granted' | 'denied'>
  onChange: (cb: (state: ConsentState) => void) => () => void
}

• ready resolves once the policy and the cookie are read, before any component renders.
• trigger() wraps useScriptTriggerConsent from @nuxt/scripts. It resolves the moment the vendor becomes allowed, so the script loads without a reload. If the vendor is never allowed, it never resolves.
• The plugin runs with enforce: 'pre', so the provider exists before your own plugins run.

Events and hooks

Three ways to hear about a decision. None of them carries the visitor's consent id.

// 1. Nuxt runtime hook (typed)
nuxtApp.hook('consent-manager:change', (state) => { /* ConsentState */ })

// 2. DOM event, for code outside Vue (a theme extension, a plain script)
window.addEventListener('revenexx:consent', (e) => {
  const state = (e as CustomEvent).detail // ConsentState
})

// 3. Subscription
const off = useNuxtApp().$consentProvider.onChange((state) => { /* … */ })

They fire after each decision (accept, reject, save, load once, withdraw), not on page load. To read the state on page load, use useConsents().state.

Google Consent Mode v2

While the policy's google_consent_mode is basic (also when no policy could be loaded), the module writes an inline script as the first <head> entry (tagPriority: 'critical'):

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 })
gtag('set', 'ads_data_redaction', true)

For a returning visitor, a gtag('consent', 'update', …) with their current signals follows in the same script. Every later decision pushes another update. Which signals a granted purpose releases is set per purpose in the policy (google_signals). Necessary and non-objected legitimate-interest purposes count as granted. With google_consent_mode: off nothing is written.

Load GA4 or GTM through @nuxt/scripts with a trigger from the provider. Do not configure a second consent default in the tag: the default belongs to this module. See docs/recipes.md → Google Consent Mode.

Server routes

The module adds two Nitro routes. The browser talks only to these routes and never to the gateway directly.

If writing a record fails, the decision still applies in the browser. The record is kept in localStorage (rvx_consent_pending, the last 10) and sent again on the next page view.

Recipes

Customising the banner through slots, a fully headless banner, YouTube behind <ConsentGate>, Google Consent Mode with GA4/GTM, the privacy-page link, editor hosts, local development against a tenant and running with the Tag Manager are collected in the cookbook → docs/recipes.md.

TypeScript

The public types are exported from the package root:

import type {
  ConsentProvider, ConsentState, Decision, LegalBasis, GoogleSignal,
  DeliveredPolicy, PolicyPurpose, PolicyVendor, BannerTexts, LocalizedPurpose, LocalizedVendor,
  ConsentCookie, RecordAction, RecordSurface, ModuleOptions,
} from '@revenexx/consent-manager-nuxt'

The module augments #app: NuxtApp.$consentProvider and the runtime hook 'consent-manager:change' are typed.

Compatibility

Troubleshooting

• No banner at all. Open /_consent-manager/policy in the browser and look at reason: not_configured means no credentials (see Credentials), nothing_published means no policy has been published for this tenant and market, and unavailable means the gateway could not be reached. Also check you are not on an editor host or path (*.theme.rvnxx.site, /admin, /preview).
• A script never loads after "Accept all". The vendor and purpose codes passed to trigger() or <ConsentGate> must exist in the published policy, and the purpose must be one the vendor serves. An unknown code is never allowed.
• The page reloads after a decision. This is intended when a decision revokes a vendor that was allowed before, because a loaded script cannot be unloaded. Turn it off with reloadOnRevoke: false if you handle it yourself.
• The banner shows again for returning visitors. A material policy version was published, or consent_lifetime_days passed. Both are meant to ask again.
• The banner appears on the privacy page. Add the page's path to banner_exempt_paths in the policy. On those paths the banner is shown as a bar, so the page stays readable.
• useConsents() needs the @revenexx/consent-manager-nuxt module. The composable was called outside the Nuxt app's component tree, or the module is not in modules.
• Records fail with 503. The record route has no credentials, so the decision only lives in the cookie. Configure credentials.

Related packages

• @revenexx/tag-manager-nuxt: loads the marketing tags configured in the revenexx Tag Manager behind this module's $consentProvider. Neither package imports the other.
• @nuxt/scripts: the loader trigger() plugs into.

A note on legal bases

This module carries out what the published policy states: which purposes exist, which legal basis each one has, which vendors serve them. It does not decide whether a basis fits a given processing, and nothing in this README is legal advice. The merchant chooses and is responsible for the legal bases, texts and vendors in the Consent Manager app.

Development and releasing

pnpm install
pnpm dev:prepare && pnpm dev                    # playground/
pnpm lint && pnpm test:types && pnpm test && pnpm build

See CONTRIBUTING.md. Releases are automated with Changesets and npm trusted publishing, so no tokens are involved:

1. pnpm changeset: choose a bump and describe the change, then commit the generated file.
2. On push to main, the Release workflow opens a "Version Packages" PR.
3. Merging that PR bumps the version, updates CHANGELOG.md and publishes to npm with provenance.

License

MIT © revenexx