Nuxt GTM

https://github.com/zadigetvoltaire/nuxt-gtm
Admin
Nuxt Google Tag Manager module integrated with Nuxt Devtools for Nuxt 3, serving as a wrapper for...
Tokens:36,339
Snippets:219
Trust Score:5
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Recommended setup with runtimeConfig.public.gtm

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/configuration.md

Recommended setup from the README Quick Setup. Configures the GTM module using runtimeConfig.public.gtm, which allows overriding configuration with environment variables. Includes the same options as the gtm key setup.

```ts
export default defineNuxtConfig({
  modules: ['@zadigetvoltaire/nuxt-gtm'],
  runtimeConfig: {
    public: {
      gtm: {
        id: 'GTM-xxxxxx',
        queryParams: {
          gtm_auth: 'AB7cDEf3GHIjkl-MnOP8qr',
          gtm_preview: 'env-4',
          gtm_cookies_win: 'x'
        },
        defer: false,
        compatibility: false,
        nonce: '2726c7f26c',
        enabled: true,
        debug: true,
        loadScript: true,
        enableRouterSync: true,
        ignoredViews: ['homepage'],
        trackOnNextTick: false,
        devtools: true
      }
    }
  }
})
```

--------------------------------

### Recommended setup with gtm config key

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/configuration.md

Recommended setup from the README Quick Setup. Configures the GTM module with the gtm key, including id, queryParams, and various options like defer, compatibility, nonce, enabled, debug, loadScript, enableRouterSync, ignoredViews, trackOnNextTick, and devtools.

```ts
export default defineNuxtConfig({
  modules: ['@zadigetvoltaire/nuxt-gtm'],
  gtm: {
    id: 'GTM-xxxxxx',                       // string, string[], or GtmIdContainer[]
    queryParams: {
      gtm_auth: 'AB7cDEf3GHIjkl-MnOP8qr',
      gtm_preview: 'env-4',
      gtm_cookies_win: 'x'
    },
    defer: false,
    compatibility: false,
    nonce: '2726c7f26c',
    enabled: true,
    debug: true,
    loadScript: true,
    enableRouterSync: true,
    ignoredViews: ['homepage'],
    trackOnNextTick: false,
    devtools: true
  }
})
```

--------------------------------

### Composition API usage of useGtm()

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/use-gtm.md

Example of using useGtm() in a Vue component's setup script. It shows how to trigger events and views, with optional chaining because useGtm() can return undefined.

```vue
<script lang="ts" setup>
const gtm = useGtm() // auto-imported by the module (addImports)

function triggerEvent() {
  gtm?.trackEvent({
    event: 'event name',
    category: 'category',
    action: 'click',
    label: 'My custom component trigger',
    value: 5000,
    noninteraction: false
  })
}

function triggerView() {
  gtm?.trackView('Home', '/')
}
</script>
```

--------------------------------

### Usage examples for hasScript

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/core-utils.md

Shows how to import and use hasScript. The first example checks for the default GTM script; the second checks for a custom proxy URL. Both log a message if the script is not present.

```typescript
import { hasScript } from '@gtm-support/vue-gtm'
if (!hasScript()) {
  console.log('GTM script not loaded yet')
}
if (!hasScript('https://my-gtm-proxy.example/gtm.js')) {
  // custom server-side GTM proxy not present
}
```

--------------------------------

### Install @zadigetvoltaire/nuxt-gtm with pnpm, yarn, and npm

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/README.md

Install the module as a dev dependency using your preferred package manager. The commands are equivalent alternatives; choose one.

```bash
# Using pnpm
pnpm add -D @zadigetvoltaire/nuxt-gtm

# Using yarn
yarn add --dev @zadigetvoltaire/nuxt-gtm

# Using npm
npm install --save-dev @zadigetvoltaire/nuxt-gtm
```

--------------------------------

### enable method usage example

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

Example usage of the enable method. Calling enable() re-enables and loads scripts if not present; enable(false) disables; enable(true, customUrl) enables with a custom source check.

```typescript
const gtm = useGtm()
gtm?.enable()                    // (re-)enable, loads scripts if not present
gtm?.enable(false)               // disable
gtm?.enable(true, 'https://my-cdn.example/gtm.js') // enable using custom source check
```

--------------------------------

### Usage example for loadScript

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/core-utils.md

Example of importing and calling loadScript with a GTM ID and configuration options. The onReady callback logs the script's src after loading.

```TypeScript
import { loadScript } from '@gtm-support/vue-gtm'
const script = loadScript('GTM-ABC123', {
  defer: true,
  compatibility: false,
  queryParams: { gtm_auth: 'abc123', gtm_preview: 'env-4', gtm_cookies_win: 'x' },
  nonce: '2726c7f26c',
  onReady: ({ id, script }) => console.log('ready', id, script.src)
})
```

--------------------------------

### Catch install failure with useGtm

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/errors.md

Shows how to check whether the GTM plugin installed successfully. useGtm returns undefined if install failed, so guard app-side logic with a null check and log a warning.

```typescript
// Composition (the module auto-imports useGtm)
const gtm = useGtm()   // undefined if install failed

// Wrap app-side logic defensively
if (!gtm) {
  logger.warn('GTM unavailable: plugin install failed (check gtm.id)')
}
```

--------------------------------

### useGtm(): GtmPlugin | undefined

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/use-gtm.md

Returns the GTM plugin instance for use in Composition API setup methods. Returns undefined if the plugin was not installed.

```APIDOC
## useGtm(): GtmPlugin | undefined

### Description
Returns the GTM plugin instance for use in Composition API setup methods. Returns undefined if the plugin was not installed.

### Method
useGtm

### Endpoint
useGtm()

### Parameters
None

### Return Value
- **GtmPlugin | undefined** - The GTM plugin instance if installed, otherwise undefined.

### Example
```vue
<script lang="ts" setup>
const gtm = useGtm() // auto-imported by the module (addImports)

function triggerEvent() {
  gtm?.trackEvent({
    event: 'event name',
    category: 'category',
    action: 'click',
    label: 'My custom component trigger',
    value: 5000,
    noninteraction: false
  })
}

function triggerView() {
  gtm?.trackView('Home', '/')
}
</script>
```
```

--------------------------------

### createGtm implementation

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/use-gtm.md

JavaScript implementation of createGtm from dist/index.js. It returns a Vue plugin object with an install function that calls the install function with the provided options.

```javascript
function createGtm(options) {
  return { install: (app) => install(app, options) };
}
```

--------------------------------

### Composition API - useGtm composable example

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/README.md

Example of using the useGtm composable in a Vue component with the Composition API. It shows how to track events and views using the gtm instance.

```vue
<template>
  <button @click="triggerEvent">
    Trigger event!
  </button>
  <button @click="triggerView">
    Trigger event!
  </button>
</template>

<script lang="ts" setup>
  const gtm = useGtm() // auto-imported by the module

  function triggerEvent() {
    gtm.trackEvent({
      event: 'event name',
      category: 'category',
      action: 'click',
      label: 'My custom component trigger',
      value: 5000,
      noninteraction: false,
    })
  }

  function triggerView() {
    gtm.trackView('Home', '/')
  }
</script>
```

--------------------------------

### dataLayer() Usage Example

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

Shows how to obtain the data layer with useGtm().dataLayer() and push a custom event only if the layer is available. The event is pushed with an event name and arbitrary data.

```typescript
const gtm = useGtm()
const layer = gtm?.dataLayer()
if (layer) layer.push({ event: 'custom', foo: 'bar' })
```

--------------------------------

### DevTools UI Development and Production Setup

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/devtools-ui.md

Comments explaining the development and production build process for the DevTools UI. In development, the Nuxt dev server proxies /__nuxt-gtm to the client dev server on port 3300. In production, the built client is served by sirv middleware at /__nuxt-gtm on the Vite server.

```typescript
// Development: client not built yet
// pnpm dev  →  nuxi dev client --port 3300  (client:dev script)
// The nuxt dev server proxies /__nuxt-gtm to http://localhost:3300/__nuxt-gtm

// Production build (prepack): dist/client is served by sirv middleware
// at /__nuxt-gtm on the Vite server
```

--------------------------------

### GtmSupport Class

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

The GtmSupport class provides methods to manage GTM container loading, debug mode, dataLayer access, and tracking of views and events. It is instantiated once during plugin installation.

```APIDOC
## GtmSupport Class

### Description
The GtmSupport class is the core tracking class behind the plugin instance returned by `useGtm()` and `this.$gtm`. It manages GTM container loading, debug mode, dataLayer access, and tracking of views and events.

### Import Path
```ts
import { GtmSupport } from '@gtm-support/vue-gtm'         // re-exported
import { GtmSupport } from '@gtm-support/core'
```

### Type Declaration
```ts
export declare class GtmSupport {
    /** GTM Container ID. */
    readonly id: string | string[] | GtmIdContainer[];
    /** GTM Support Options. */
    readonly options: Omit<GtmSupportOptions, 'id'>;
    readonly scriptElements: HTMLScriptElement[];
    constructor(options: GtmSupportOptions);
    isInBrowserContext: () => boolean;
    enabled(): boolean;
    enable(enabled?: boolean, source?: string): void;
    debugEnabled(): boolean;
    debug(enable: boolean): void;
    dataLayer(): DataLayerObject[] | false;
    trackView(screenName: string, path: string, additionalEventData?: Record<string, any>): void;
    trackEvent({ event, category, action, label, value, noninteraction, ...rest }?: TrackEventOptions): void;
}
```

### Properties
| Property | Type | Description |
|---|---|---|
| `id` | `string \| string[] \| GtmIdContainer[]` (readonly) | The GTM container id(s) exactly as passed in options |
| `options` | `Omit<GtmSupportOptions, 'id'>` (readonly) | The resolved options after constructor normalization (`id` removed; runtime defaults applied) |
| `scriptElements` | `HTMLScriptElement[]` | Script elements created by `enable()` calls (empty until `enable(true)` runs) |

### Constructor
`constructor(options: GtmSupportOptions)`

Creates a new GtmSupport instance with the given options.

### Methods

#### isInBrowserContext
`isInBrowserContext(): boolean`

Returns whether the current context is a browser.

#### enabled
`enabled(): boolean`

Returns whether GTM is enabled.

#### enable
`enable(enabled?: boolean, source?: string): void`

Enables or disables GTM. When enabled, it loads the GTM script. The `source` parameter can be used to identify the caller.

#### debugEnabled
`debugEnabled(): boolean`

Returns whether debug mode is enabled.

#### debug
`debug(enable: boolean): void`

Enables or disables debug mode.

#### dataLayer
`dataLayer(): DataLayerObject[] | false`

Returns the dataLayer array, or `false` if not in browser context.

#### trackView
`trackView(screenName: string, path: string, additionalEventData?: Record<string, any>): void`

Tracks a page view with the given screen name and path. Optional additional event data can be provided.

#### trackEvent
`trackEvent({ event, category, action, label, value, noninteraction, ...rest }?: TrackEventOptions): void`

Tracks a custom event with the given options. The options object can include `event`, `category`, `action`, `label`, `value`, `noninteraction`, and any additional properties.
```

--------------------------------

### Configure GTM in nuxt.config.ts

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/README.md

Add GTM configuration under the gtm key or runtimeConfig.public.gtm. The example shows all available options with comments explaining each. The id can be a single string, array of strings, or array of objects with queryParams. Other options control script loading, debugging, router sync, and more.

```ts
export default defineNuxtConfig({
  ...
  gtm: {
    id: 'GTM-xxxxxx', // Your GTM single container ID, array of container ids ['GTM-xxxxxx', 'GTM-yyyyyy'] or array of objects [{id: 'GTM-xxxxxx', queryParams: { gtm_auth: 'abc123', gtm_preview: 'env-4', gtm_cookies_win: 'x'}}, {id: 'GTM-yyyyyy', queryParams: {gtm_auth: 'abc234', gtm_preview: 'env-5', gtm_cookies_win: 'x'}}], // Your GTM single container ID or array of container ids ['GTM-xxxxxx', 'GTM-yyyyyy']
    queryParams: {
      // Add URL query string when loading gtm.js with GTM ID (required when using custom environments)
      gtm_auth: 'AB7cDEf3GHIjkl-MnOP8qr',
      gtm_preview: 'env-4',
      gtm_cookies_win: 'x',
    },
    defer: false, // Script can be set to `defer` to speed up page load at the cost of less accurate results (in case visitor leaves before script is loaded, which is unlikely but possible). Defaults to false, so the script is loaded `async` by default
    compatibility: false, // Will add `async` and `defer` to the script tag to not block requests for old browsers that do not support `async`
    nonce: '2726c7f26c', // Will add `nonce` to the script tag
    enabled: true, // defaults to true. Plugin can be disabled by setting this to false for Ex: enabled: !!GDPR_Cookie (optional)
    debug: true, // Whether or not display console logs debugs (optional)
    loadScript: true, // Whether or not to load the GTM Script (Helpful if you are including GTM manually, but need the dataLayer functionality in your components) (optional)
    enableRouterSync: true, // Pass the router instance of your app to automatically sync with router (optional)
    ignoredViews: ['homepage'], // Don't trigger events for specified router names (optional)
    trackOnNextTick: false, // Whether or not call trackView in Vue.nextTick
    devtools: true, // (optional)
  }
  ...
  runtimeConfig: {
    public: {
      gtm: {
        id: 'GTM-xxxxxx',
        queryParams: {
          gtm_auth: 'AB7cDEf3GHIjkl-MnOP8qr',
          gtm_preview: 'env-4',
          gtm_cookies_win: 'x',
        },
        defer: false,
        compatibility: false,
        nonce: '2726c7f26c',
        enabled: true,
        debug: true,
        loadScript: true,
        enableRouterSync: true,
        ignoredViews: ['homepage'],
        trackOnNextTick: false,
        devtools: true,
      }
    }
  }
})
```

--------------------------------

### Default export of `defineNuxtModule<ModuleOptions>` from `src/module.ts`

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/module.md

This is the complete module factory definition. It sets the module metadata, defaults, and the setup function that merges options with runtime config, adds the runtime plugin, registers the `useGtm` composable, and conditionally sets up DevTools UI.

```typescript
export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: '@zadigetvoltaire/nuxt-gtm',
    configKey: 'gtm',
    compatibility: {
      nuxt: '^3.0.0'
    }
  },
  // @ts-ignore
  defaults: {
    devtools: true
  },
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    const moduleOptions: ModuleOptions = defu(nuxt.options.runtimeConfig.public.gtm, options)

    nuxt.options.runtimeConfig.public.gtm = moduleOptions

    // Do not add the extension since the `.ts` will be transpiled to `.mjs` after `npm run prepack`
    addPlugin(resolver.resolve('./runtime/plugin'))

    addImports({
      name: 'useGtm',
      as: 'useGtm',
      from: '@gtm-support/vue-gtm'
    })

    if (options.devtools) {
      setupDevToolsUI(nuxt, resolver)
    }
  }
})
```

--------------------------------

### Usage in nuxt.config.ts

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/runtime-plugin.md

Example configuration for a consuming application. The gtm option is passed to the module and used by the runtime plugin. enableRouterSync is translated to vueRouter, and ignoredViews skips the router guard for the named route.

```TypeScript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@zadigetvoltaire/nuxt-gtm'],
  gtm: {
    id: 'GTM-ABC123',
    enableRouterSync: true,             // → passed as vueRouter to createGtm
    ignoredViews: ['checkout-success'], // router guard skips this route name
    trackOnNextTick: false
  }
})
```

--------------------------------

### Error-guarded usage with enable()

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

Checks if the GTM plugin is installed, throwing an error otherwise. Enable triggers script loading and can throw if a custom parentElement is invalid. Wrap in try/catch to log errors.

```ts
// Error-guarded usage; enable() triggers script loading
const gtm = useGtm()
if (!gtm) throw new Error('GTM plugin not installed (client-only)')
try {
  gtm.enable(true)
  gtm.trackEvent({ event: 'signup', value: 1 })
} catch (error) {
  // loadScript throws when a custom parentElement is invalid (see errors.md)
  console.error(error)
}
```

--------------------------------

### Development Commands

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/README.md

Commands to set up the development environment, run the dev server, use the playground, lint, and run tests.

```bash
# Install dependencies, prepare apps & run dev server
make start

# Run dev server
pnpm dev

# Develop with playground, with bundled client ui
pnpm play:prod

# Run ESLint
pnpm lint

# Run Vitest
pnpm test
pnpm test:watch
```

--------------------------------

### constructor(options: GtmSupportOptions)

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

Creates a new GtmSupport instance. Validates all provided GTM IDs, stores the id, and normalizes options with runtime defaults.

```APIDOC
## constructor(options: GtmSupportOptions)

### Description
Creates a new GtmSupport instance. Validates all provided GTM IDs, stores the id, and normalizes options with runtime defaults.

### Method
Constructor

### Signature
```ts
constructor(options: GtmSupportOptions)
```

### Parameters
- **options** (GtmSupportOptions) - Required - See types.md. `id` is required.

### Behavior
- Validates every id: if `options.id` is an array it iterates entries — strings are validated directly, objects are validated via `idOrObject.id` — otherwise `options.id` is validated. Validation is `assertIsGtmId`; an invalid id throws an `Error`.
- Stores `this.id = options.id`.
- Normalizes `this.options` merging runtime defaults before the given options:

```js
this.options = {
  enabled: true,
  debug: false,
  loadScript: true,
  defer: false,
  compatibility: false,
  ...options
};
delete this.options.id;
```

So `enabled` defaults to `true`, `debug` to `false`, `loadScript` to `true`, `defer` to `false`, `compatibility` to `false`.
```

--------------------------------

### setupDevToolsUI: serve DevTools UI and register custom tab

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/devtools-ui.md

Wires the Nuxt DevTools integration: serves the module's own UI at `/__nuxt-gtm` and registers a custom DevTools tab. In production builds it serves the built client via sirv; otherwise it proxies to the local dev server on port 3300. The tab is named 'nuxt-gtm' with title 'Nuxt GTM' and an iframe view.

```ts
export function setupDevToolsUI (nuxt: Nuxt, resolver: Resolver) {
  const clientPath = resolver.resolve('./client')
  const isProductionBuild = existsSync(clientPath)

  // Serve production-built client (used when package is published)
  if (isProductionBuild) {
    nuxt.hook('vite:serverCreated', async (server) => {
      const sirv = await import('sirv').then(r => r.default || r)
      server.middlewares.use(
        DEVTOOLS_UI_ROUTE,
        sirv(clientPath, { dev: true, single: true })
      )
    })
  } else {
    nuxt.hook('vite:extendConfig', (config) => {
      config.server = config.server || {}
      config.server.proxy = config.server.proxy || {}
      config.server.proxy[DEVTOOLS_UI_ROUTE] = {
        target: 'http://localhost:' + DEVTOOLS_UI_LOCAL_PORT + DEVTOOLS_UI_ROUTE,
        changeOrigin: true,
        followRedirects: true,
        rewrite: path => path.replace(DEVTOOLS_UI_ROUTE, '')
      }
    })
  }

  // @ts-expect-error
  nuxt.hook('devtools:customTabs', (tabs) => {
    tabs.push({
      // unique identifier
      name: 'nuxt-gtm',
      // title to display in the tab
      title: 'Nuxt GTM',
      // any icon from Iconify, or a URL to an image
      icon: 'carbon:text-link-analysis',
      // iframe view
      view: {
        type: 'iframe',
        src: DEVTOOLS_UI_ROUTE
      }
    })
  })
}
```

--------------------------------

### Release Command

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/README.md

Command to generate the changelog, bump the package version, create and push a tag, and trigger the publish pipeline. Should only be executed on the main branch.

```bash
pnpm release
```

--------------------------------

### Runtime plugin definition (src/runtime/plugin.ts)

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/runtime-plugin.md

The default export of src/runtime/plugin.ts is a Nuxt plugin that installs the Vue GTM plugin on the client. It reads options from nuxt.$config.public.gtm, conditionally passes the router to enable router sync, and installs the plugin via nuxt.vueApp.use().

```TypeScript
import { defineNuxtPlugin, useRouter } from 'nuxt/app'
import { createGtm, type VueGtmUseOptions } from '@gtm-support/vue-gtm'
// @ts-ignore

export default defineNuxtPlugin((nuxt) => {
  if (process.client) {
    const options = nuxt.$config.public.gtm

    const router = useRouter()

    const pluginOptions: VueGtmUseOptions = {
      ...options,
      vueRouter: options.enableRouterSync && router ? router as VueGtmUseOptions['vueRouter'] : undefined
    }

    nuxt.vueApp.use(createGtm(pluginOptions))
  }
})
```

--------------------------------

### useGtm() TypeScript declaration

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/use-gtm.md

The official type declaration for useGtm() from @gtm-support/vue-gtm. It returns the GTM plugin instance or undefined if not installed.

```typescript
/**
 * Returns GTM plugin instance to be used via Composition API inside setup method.
 *
 * @returns The Vue GTM instance if the it was installed, otherwise `undefined`.
 */
export declare function useGtm(): GtmPlugin | undefined;
```

--------------------------------

### enable(enabled?, source?): void

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

Enables or disables GTM support and optionally loads the GTM script if not already present.

```APIDOC
## enable(enabled?, source?): void

### Description
Enables or disables GTM support and optionally loads the GTM script if not already present.

### Method
enable

### Signature
`enable(enabled?: boolean, source?: string): void`

### Parameters
- **enabled** (boolean) - Optional - New enabled state (`this.options.enabled = enabled`). Defaults to `true`.
- **source** (string) - Optional - Script URL to test against `hasScript(source)`; defaults to `https://www.googletagmanager.com/gtm.js` inside `hasScript`.

### Behavior
Sets `options.enabled`. Then, if in browser context and enabled and `!hasScript(source)` and `options.loadScript`, loads scripts: for an array `id`, one `loadScript` call per entry (string entries use `{...this.options}`; object entries use `{...this.options, queryParams: id.queryParams}` — note the object's `queryParams` replaces, not merges); for a scalar id, one `loadScript(this.id, {...this.options})`.

### Example
```ts
const gtm = useGtm()
gtm?.enable()                    // (re-)enable, loads scripts if not present
gtm?.enable(false)               // disable
gtm?.enable(true, 'https://my-cdn.example/gtm.js') // enable using custom source check
```
```

--------------------------------

### Options API usage of $gtm

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/use-gtm.md

Example of using this.$gtm in an Options API component's methods to track an event.

```typescript
export default {
  methods: {
    triggerEvent() {
      this.$gtm.trackEvent({
        event: 'event name',
        category: 'category',
        action: 'click',
        label: 'My custom component trigger',
        value: 5000,
        noninteraction: false
      })
    }
  }
}
```

--------------------------------

### Using assertIsGtmId with try-catch

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/core-utils.md

Example of using assertIsGtmId in a try-catch block. Valid id passes, invalid id throws an error with a suggestion.

```typescript
import { assertIsGtmId } from '@gtm-support/vue-gtm'
try {
  assertIsGtmId('GTM-ABC123') // ok
  assertIsGtmId('gtm-abc123') // throws: suggestion 'GTM-ABC123'
} catch (error) {
  console.error((error as Error).message)
}
```

--------------------------------

### Basic view and event tracking with useGtm

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

Calls trackView for a page view and trackEvent for a click event. Optionally passes additional view data as a third argument, used by the router guard as well.

```ts
// Basic view + event tracking
const gtm = useGtm()
gtm?.trackView('Home', '/')
gtm?.trackEvent({ event: 'click', category: 'button', action: 'click', label: 'hero-cta' })

// With additional view data (used by the router guard as well)
gtm?.trackView('Product', '/p/42', { pageType: 'product' })
```

--------------------------------

### createGtm(options: VueGtmUseOptions): VueGtmPlugin

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/use-gtm.md

Creates a Vue plugin instance for Google Tag Manager integration. The returned plugin is install-ready and should be passed to app.use(). The plugin initializes GTM support, sets up the $gtm global property, and optionally loads the GTM script and router guard.

```APIDOC
## createGtm(options: VueGtmUseOptions): VueGtmPlugin

### Description
Creates a Vue plugin instance for Google Tag Manager integration. The returned plugin is install-ready and should be passed to `app.use()`. The plugin initializes GTM support, sets up the `$gtm` global property, and optionally loads the GTM script and router guard.

### Method
createGtm

### Signature
```ts
export declare function createGtm(options: VueGtmUseOptions): VueGtmPlugin;
```

### Parameters
#### Options
- **options** (VueGtmUseOptions) - Required - Plugin options; see [types.md](../types.md). The Nuxt module builds this object from the merged `runtimeConfig.public.gtm` plus `vueRouter`.

### Return Value
- **VueGtmPlugin** - A Vue plugin defined as `{ install: (app) => install(app, options) }`. It is already the `install`-ready object; consumers never call it directly under this Nuxt module — the runtime plugin passes it to `nuxt.vueApp.use(...)`.

### Side Effects of install(app, options)
Called by `app.use(plugin)`:
- Defaults `trackOnNextTick` to `false`.
- Creates `gtmPlugin = new GtmSupport(options)` (a module-level singleton shared with `useGtm()`).
- Sets `app.config.globalProperties.$gtm = gtmPlugin`.
- If in a browser context (client):
  - If `options.vueRouter` is set, initializes the router guard.
  - If `gtmPlugin.options.enabled` and `gtmPlugin.options.loadScript` are both truthy, loads the GTM script(s): for array ids, calls `loadScript` per entry (merging `id.queryParams` over options for object entries), otherwise `loadScript(options.id, options)`.
- `app.provide("gtm", options)` — injects the **options object** under the key `gtm` (not the plugin instance).

### Import Paths
```ts
import { useGtm } from '@gtm-support/vue-gtm'   // or rely on the Nuxt auto-import
import { createGtm, type VueGtmUseOptions } from '@gtm-support/vue-gtm'
```
```

--------------------------------

### GtmSupportOptions

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/types.md

Configuration options for the GTM support plugin. This interface defines all available settings for initializing the plugin with a GTM container ID, custom query parameters, script loading behavior, and other options.

```APIDOC
## GtmSupportOptions

### Description
Configuration options for the GTM support plugin. This interface defines all available settings for initializing the plugin with a GTM container ID, custom query parameters, script loading behavior, and other options.

### Fields

- **id** (`string | string[] | GtmIdContainer[]`) - Required - Container id, id array, or array of `{ id, queryParams }` objects (JSDoc example includes per-container `queryParams` with `gtm_auth`, `gtm_preview`, `gtm_cookies_win`)
- **queryParams** (`GtmQueryParams`) - Optional - Query string when loading `gtm.js` (required for custom envs)
- **defer** (`boolean`) - Optional - `defer` loading; default `false` (= `async`)
- **compatibility** (`boolean`) - Optional - Add `async` + `defer`; default `false`
- **nonce** (`string`) - Optional - CSP nonce for the script tag
- **source** (`string`) - Optional - Script URL; default `https://www.googletagmanager.com/gtm.js`
- **enabled** (`boolean`) - Optional - Disable plugin; default `true`
- **debug** (`boolean`) - Optional - Console debug logs; default `false`
- **loadScript** (`boolean`) - Optional - Auto-load the GTM script; default `true`
- **trackViewEventProperty** (`string`) - Optional - `event` value of view events; default `content-view`

### Accepted By

- `new GtmSupport(options)`
- Embedded in `VueGtmUseOptions`
- `ModuleOptions` inherits every field except `vueRouter`.
```

--------------------------------

### Configure module via `modules` array in `nuxt.config.ts`

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/module.md

Shows how to include the module by string in the `modules` array and set the `gtm` configuration key with an ID and router sync option.

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@zadigetvoltaire/nuxt-gtm'],
  gtm: {
    id: 'GTM-XXXXXX',
    enableRouterSync: true
  }
})
```

--------------------------------

### Router Guard (view tracking)

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/use-gtm.md

Describes the automatic view tracking behavior when a vueRouter is passed and the plugin installs in a browser context. The guard is registered with vueRouter.afterEach and tracks views based on route changes.

```APIDOC
## Router Guard (view tracking)

### Description
Automatically tracks page views when a vueRouter is provided and the plugin runs in a browser context (enableRouterSync: true). The guard is registered with vueRouter.afterEach and fires on every navigation.

### Trigger
- Registered with `vueRouter.afterEach(async (to, from, failure) => {...})`
- Only active when a `vueRouter` is passed and the plugin installs in a browser context (under this Nuxt module: `enableRouterSync: true`)

### Behavior

| Condition | Behavior |
|---|---|
| `typeof to.name !== 'string'` | Return early; no event tracked |
| `ignoredViews` is an array containing `to.name` | Return early; no event tracked |
| `ignoredViews` is a function that returns `true` for `(to, from)` | Return early; no event tracked |
| `to.meta.gtm` is a string and truthy | `name = to.meta.gtm` (per-route override of the event name) |
| otherwise | `name = to.name` |
| navigation failure with `failure.type & 4` (aborted) | Logged when `debugEnabled()`: `'${name}' not tracked due to navigation aborted` |
| navigation failure with `failure.type & 8` (cancelled) | Logged when `debugEnabled()`: `'${name}' not tracked due to navigation cancelled` |
| successful navigation | `gtm.trackView(name, fullUrl, additionalEventData)` where `fullUrl = base + '/' + to.fullPath` (leading `/` stripped from `to.fullPath`; `base` taken from `vueRouter.options.history.base`) and `additionalEventData` = `{ ...await vueRouterAdditionalEventData(to, from), ...to.meta.gtmAdditionalEventData }` |
| `trackOnNextTick` truthy | the `trackView` call is wrapped in `nextTick(() => ...)` |

```

--------------------------------

### GtmIdContainer interface

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/types.md

Used inside id-related option fields to specify a GTM container ID and optional per-container query parameters. In the Vue plugin install path, queryParams are merged over top-level options; in GtmSupport.enable() they replace them.

```typescript
export interface GtmIdContainer {
    id: string;
    queryParams?: GtmQueryParams;
}
```

--------------------------------

### Import core utilities from @gtm-support/vue-gtm

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/core-utils.md

Import the core utilities loadScript, hasScript, assertIsGtmId, and GTM_ID_PATTERN from the package.

```typescript
import { loadScript, hasScript, assertIsGtmId, GTM_ID_PATTERN } from '@gtm-support/vue-gtm'
```

--------------------------------

### Configure module via programmatic import in `nuxt.config.ts`

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/module.md

Shows how to import the module and use it directly in the `modules` array, typical for test fixtures; includes the `devtools` option.

```typescript
// Imported programmatically (test fixtures use this form, test/fixtures/basic/nuxt.config.ts)
import nuxtGtm from '@zadigetvoltaire/nuxt-gtm'

export default defineNuxtConfig({
  modules: [nuxtGtm],
  gtm: { devtools: true, id: 'GTM-XXXXXX', enableRouterSync: true }
})
```

--------------------------------

### Constructor signature: constructor(options: GtmSupportOptions)

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

The constructor for GTM support. Validates every id in `options.id` using `assertIsGtmId` and throws an `Error` on invalid ids. It stores `this.id = options.id` and normalizes `this.options` by merging runtime defaults before the provided options, then deletes the `id` property.

```ts
constructor(options: GtmSupportOptions)
```

--------------------------------

### $gtm — Options API global property

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/use-gtm.md

The GTM plugin instance is available on any component instance as this.$gtm for use in Options API methods.

```APIDOC
## $gtm — Options API global property

### Description
The GTM plugin instance is available on any component instance as this.$gtm for use in Options API methods.

### Method
$gtm

### Endpoint
this.$gtm

### Parameters
None

### Return Value
- **GtmPlugin** - The GTM plugin instance.

### Example
```ts
export default {
  methods: {
    triggerEvent() {
      this.$gtm.trackEvent({
        event: 'event name',
        category: 'category',
        action: 'click',
        label: 'My custom component trigger',
        value: 5000,
        noninteraction: false
      })
    }
  }
}
```
```

--------------------------------

### enabled(): boolean

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

Returns whether the plugin is enabled, based on the normalized options. Since options.enabled is always defined after the constructor, this effectively returns options.enabled.

```APIDOC
## enabled(): boolean

### Description
Returns whether the plugin is enabled, based on the normalized options. Since options.enabled is always defined after the constructor, this effectively returns options.enabled.

### Method
Method

### Signature
```ts
enabled(): boolean;
```

### Returns
- **boolean** - `this.options.enabled ?? true` — whether the plugin is enabled. `options.enabled` is always defined after the constructor, so this is effectively `options.enabled`.
```

--------------------------------

### ModuleOptions

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/types.md

Configuration options for the Nuxt GTM module. Extends VueGtmUseOptions (excluding vueRouter) and adds Nuxt-specific fields for router sync and DevTools integration.

```APIDOC
## ModuleOptions

### Description
Configuration options for the Nuxt GTM module. Extends VueGtmUseOptions (excluding vueRouter) and adds Nuxt-specific fields for router sync and DevTools integration.

### Type
```ts
export interface ModuleOptions extends Omit<VueGtmUseOptions, 'vueRouter'> {
  enableRouterSync?: boolean
  /**
   * Enable Nuxt Devtools integration
   *
   * @default true
   */
  devtools?: boolean
}
```

### Fields

#### id (inherited)
- **Type**: `string | string[] | GtmIdContainer[]`
- **Required**: Yes
- **Description**: GTM container id(s)

#### enableRouterSync
- **Type**: `boolean`
- **Required**: No
- **Description**: Pass the Nuxt router as `vueRouter` to the GTM plugin; defaults to off

#### devtools
- **Type**: `boolean`
- **Required**: No
- **Description**: Enable the Nuxt DevTools tab; module default `true`

#### vueRouterAdditionalEventData (inherited)
- **Type**: `(to: RouteLocationNormalized, from: RouteLocationNormalized) => Record<string, any> | Promise<Record<string, any>>`
- **Required**: No
- **Description**: Derive extra event data after navigation

#### ignoredViews (inherited)
- **Type**: `string[] | ((to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean)`
- **Required**: No
- **Description**: Router names (or predicate) for which no view event is tracked

#### trackOnNextTick (inherited)
- **Type**: `boolean`
- **Required**: No
- **Description**: Call `trackView` inside `Vue.nextTick`

#### queryParams (inherited)
- **Type**: `GtmQueryParams`
- **Required**: No
- **Description**: Query string appended to `gtm.js`

#### defer (inherited)
- **Type**: `boolean`
- **Required**: No
- **Description**: Load script with `defer` (default `false`, i.e. `async`)

#### compatibility (inherited)
- **Type**: `boolean`
- **Required**: No
- **Description**: Add both `async` and `defer` for old browsers

#### nonce (inherited)
- **Type**: `string`
- **Required**: No
- **Description**: CSP `nonce` on the script tag

#### source (inherited)
- **Type**: `string`
- **Required**: No
- **Description**: Script URL; default `https://www.googletagmanager.com/gtm.js`

#### enabled (inherited)
- **Type**: `boolean`
- **Required**: No
- **Description**: Disable the plugin without removing it; default `true`

#### debug (inherited)
- **Type**: `boolean`
- **Required**: No
- **Description**: Console debug logs; core default `false`

#### loadScript (inherited)
- **Type**: `boolean`
- **Required**: No
- **Description**: Load the GTM script automatically; default `true`

#### trackViewEventProperty (inherited)
- **Type**: `string`
- **Required**: No
- **Description**: `event` value of view events; default `content-view`

### Usage
Accepted by: Nuxt module config key `gtm`, `nuxt.config`/`nuxt.options`/`runtimeConfig.public.gtm` (schema augmentation in `src/module.ts:17-27`); consumed by the runtime plugin when building `VueGtmUseOptions` (`src/runtime/plugin.ts:12-14`).
```

--------------------------------

### Import GtmSupport from @gtm-support/vue-gtm and @gtm-support/core

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/api-reference/gtm-support.md

Shows the two import paths for the GtmSupport class: re-exported from @gtm-support/vue-gtm and directly from @gtm-support/core.

```typescript
import { GtmSupport } from '@gtm-support/vue-gtm'         // re-exported
import { GtmSupport } from '@gtm-support/core'
```

--------------------------------

### VueGtmUseOptions

Source: https://github.com/zadigetvoltaire/nuxt-gtm/blob/main/_autodocs/types.md

Configuration options for the Vue GTM plugin, extending GtmSupportOptions with Vue Router integration settings.

```APIDOC
## VueGtmUseOptions

### Description
Configuration options for the Vue GTM plugin, extending GtmSupportOptions with Vue Router integration settings.

### Fields

#### `vueRouter` (Router) - Optional
Router instance; when present, an `afterEach` guard tracks views.

#### `vueRouterAdditionalEventData` ((to, from) => Record<string, any> | Promise<Record<string, any>>) - Optional
Extra data merged into view events (`to.meta.gtmAdditionalEventData` is merged after it).

#### `ignoredViews` (string[] | ((to, from) => boolean)) - Optional
Skip view tracking for matching route names / predicate.

#### `trackOnNextTick` (boolean) - Optional
`trackView` deferred to next tick; plugin-install default `false`.

#### All `GtmSupportOptions` fields - Optional
Inherited from GtmSupportOptions.

### Usage
Accepted by: `createGtm(options)` — see [use-gtm.md](api-reference/use-gtm.md).
```
Tokens:
Raw