@stackonward/google-tag-manager-nuxt

Consent-aware Google Tag Manager composition for Nuxt. The module installs the provider-neutral analytics runtime, loads GTM through @nuxt/scripts, and registers the Google transport only in the browser.

Install

pnpm add @stackonward/google-tag-manager-nuxt @nuxt/scripts

Nuxt and Vue are peer dependencies. See Compatibility for the supported ranges.

Setup

export default defineNuxtConfig({
  modules: ["@stackonward/google-tag-manager-nuxt"],
  gtm: {
    id: process.env.NUXT_PUBLIC_GTM_ID || "",
    analytics: {
      applicationId: "product-a",
      environment: process.env.NUXT_PUBLIC_SITE_ENV || "development",
      autoCapture: {
        internalDomains: ["product.example"],
        modulePrefix: "product_",
        moduleRules: [{ selector: "header", module: "navigation" }],
      },
    },
  },
});

An empty id disables the integration by default. Setting enabled: true without an ID fails configuration instead of starting a partially configured runtime.

Options

| Option | Default | Purpose | | ---------------- | --------------------------------------------- | ------------------------------------------------------------------------ | | id | "" | GTM container ID matching GTM-[A-Z0-9]+ | | enabled | id.length > 0 | Enables script loading and the Google transport | | dataLayerName | "dataLayer" | Valid JavaScript identifier used by the GTM data layer | | defaultConsent | every storage category denied | Consent Mode defaults applied before the script loads | | grantedConsent | analytics and security granted; others denied | Consent applied after grant(); the script stays loaded | | script | {} | @nuxt/scripts bundle, proxy, Partytown, and warmup settings | | analytics | analytics module defaults | @stackonward/analytics-nuxt options, including context and autocapture |

Consent objects also accept region and wait_for_update; unknown option keys are rejected.

Consent lifecycle

The module loads GTM immediately under defaultConsent (Google Consent Mode). Granting updates Google consent to grantedConsent without waiting to load the script. Denying restores defaultConsent and keeps the script loaded. Grant or deny through the provider-neutral composable:

<script setup lang="ts">
const consent = useAnalyticsConsent();

function acceptAnalytics() {
  consent.grant();
}

function rejectAnalytics() {
  consent.deny();
}
</script>

Disposing the runtime removes the script. A missing @nuxt/scripts consent API or use after disposal fails with a typed lifecycle error instead of reporting success.

The product or consent-management platform owns persistence of the user's decision. Restore a saved grant or denial during application startup.

Generate the matching GTM container

Use stackonward analytics generate or @stackonward/google-tag-manager/container to create the matching GTM import artifact. Import it into a GTM web-container workspace, preview it, and publish the reviewed container version. This module never mutates Google account configuration.

Installed runtime

• @stackonward/analytics-nuxt for tracking, context, consent, and autocapture
• @nuxt/scripts for typed GTM script loading
• @stackonward/google-tag-manager for event validation and data-layer projection
• public runtime config under stackonwardGtm

Compatibility

• Node.js 20 or newer
• Nuxt >=3.15.0 <5
• Vue >=3.5.0 <4
• @nuxt/scripts >=1.3.0 <2

Related packages

• @stackonward/analytics-nuxt is the provider-neutral Nuxt runtime.
• @stackonward/google-tag-manager can be used without Nuxt.
• @stackonward/cli generates declarative analytics provider artifacts.

License

MIT