Registry / web-framework / vue-gtag

vue-gtag

JSON →
library3.7.0jsnpmunverified

Vue-gtag is a Global Site Tag (gtag.js) plugin designed specifically for Vue 3 applications, facilitating the integration of Google Analytics, Google Ads, and Google Marketing Platform tracking. Currently at stable version 3.7.0, the library maintains an active release cadence, with frequent minor updates and bug fixes, often addressing dependency updates or small API refinements. It distinguishes itself by providing a deeply integrated, Vue-idiomatic API, including both a global plugin for straightforward application-wide setup and a composable `useGtag()` for fine-grained control within components. Key features include automatic pageview tracking when integrated with `vue-router` (now supporting both v4 and v5), comprehensive consent management functionalities, and support for all standard `gtag.js` commands (`event`, `config`, `set`). The library aims to simplify the often complex setup of Google tracking, allowing developers to leverage Google's robust analytics platform with minimal boilerplate in their Vue projects.

npm install vue-gtag
INSTALL
IMPORT
SIG · VUE-GTAG
V
vue-gtag
web-frameworkjavascriptv3.7.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueGtag
import VueGtag from 'vue-gtag'
import { VueGtag } from 'vue-gtag'
VueGtag is the default export representing the Vue plugin for `app.use()`.
useGtag
import { useGtag } from 'vue-gtag'
import useGtag from 'vue-gtag'
The `useGtag` composable provides reactive access to gtag functions within Vue components.
GtagOptions
import type { GtagOptions } from 'vue-gtag'
import { GtagOptions } from 'vue-gtag'
Use `import type` for type-only imports to ensure proper tree-shaking and avoid runtime issues.

Demonstrates `vue-gtag` installation with Vue Router for automatic pageview tracking and manual event sending via the `useGtag` composable.

import { createApp } from 'vue'; import App from './App.vue'; import { createRouter, createWebHistory } from 'vue-router'; import VueGtag from 'vue-gtag'; // The main plugin import type { GtagOptions } from 'vue-gtag'; // Import types for clarity // 1. Setup Vue Router (optional, but recommended for pageview tracking) const router = createRouter({ history: createWebHistory(), routes: [ { path: '/', component: { template: '<div><h1>Home Page</h1><router-link to="/about">Go to About</router-link></div>' } }, { path: '/about', component: { template: '<div><h1>About Page</h1><router-link to="/">Go to Home</router-link></div>' } } ], }); // 2. Configure vue-gtag options const gtagOptions: GtagOptions = { appName: 'my-vue-app', pageTrackerScreenviewEnabled: true, // Enables automatic pageview tracking config: { id: process.env.VUE_APP_GTAG_ID ?? 'G-XXXXXXXXXX', // Use an environment variable for your GA4 Measurement ID params: { send_page_view: true, }, }, router, // Link router for automatic pageview tracking // consent: { // granted: ['analytics_storage', 'ad_storage'], // denied: [], // default: { analytics_storage: 'denied', ad_storage: 'denied' } // } }; // 3. Create and configure Vue App const app = createApp(App); app.use(router); app.use(VueGtag, gtagOptions); app.mount('#app'); // App.vue (Example component using useGtag composable) <template> <div> <router-view></router-view> <button @click="trackButtonClick">Track Interaction</button> </div> </template> <script setup lang="ts"> import { useGtag } from 'vue-gtag'; import { onMounted } from 'vue'; const { event, consent } = useGtag(); onMounted(() => { console.log('App and gtag are ready.'); // Optionally set or update consent based on user interaction // consent.update({ analytics_storage: 'granted', ad_storage: 'granted' }); }); function trackButtonClick() { event('custom_button_click', { event_category: 'engagement', event_label: 'user_interaction', value: Math.floor(Math.random() * 100) + 1, }); console.log('Custom button click event sent.'); } </script>
Debug
Known issues
breakingVue-gtag v3 is exclusively for Vue 3 projects. Migration from v2 (for Vue 2) requires a complete rewrite of plugin initialization and API calls due to fundamental changes in the Vue 3 API.
fix
Refer to the official vue-gtag documentation for Vue 3 migration guides. Update plugin initialization from `Vue.use()` to `app.use()` and replace `this.$gtag` with `useGtag()` composable.
affects: >=3.0.0
gotchaWhile `vue-router` is an optional peer dependency, automatic pageview tracking will not function without it being installed and passed to the `vue-gtag` plugin options. Manual tracking for each page change would be required otherwise.
fix
To enable automatic pageview tracking, ensure `vue-router` (v4 or v5) is installed and imported, then include `router` in your `VueGtag` plugin options: `app.use(VueGtag, { ..., router })`.
affects: >=3.0.0
gotchaImplementing Google's Consent Mode (V2) is critical for data privacy compliance. Incorrectly setting consent states (`analytics_storage`, `ad_storage`) can lead to data loss or legal non-compliance.
fix
Carefully implement the `consent` option during plugin initialization or use the `consent.update()` method from `useGtag` in response to user choices. Ensure default consent states are set correctly according to regional regulations.
affects: >=3.5.0
gotchaAd blockers can prevent `gtag.js` scripts from loading and sending data to Google Analytics, resulting in incomplete or inaccurate analytics reports. This is a browser-level issue beyond the control of `vue-gtag`.
fix
Communicate this limitation to stakeholders. While there's no direct fix within `vue-gtag`, server-side tracking (e.g., Google Tag Manager Server-Side) can mitigate some effects of client-side ad blocking.
affects: >=3.0.0
gotchaVue 3 applications are typically ESM-first. While `vue-gtag` v3.6.3 added 'node' export conditions, attempting to use CommonJS `require()` in an ESM context or vice-versa can lead to module resolution errors.
fix
Always use `import` statements for `vue-gtag` in modern Vue CLI, Vite, or Nuxt 3 projects. If encountering issues in Node.js environments (like SSR), verify your build configuration supports ESM.
affects: >=3.0.0
gotchaEnsure the Google Analytics Measurement ID is correctly provided. A common mistake is to provide an invalid ID format or to omit the ID, leading to tracking failures.
fix
Double-check that the `id` property within the `config` object of your `VueGtag` options is a valid GA4 Measurement ID (e.g., 'G-XXXXXXXXXX'). Use environment variables for production IDs.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'event')
The `useGtag()` composable was called before `vue-gtag` was properly initialized via `app.use()`, or the `gtag.js` script has not yet loaded.
fix
Ensure `app.use(VueGtag, ...)` is called before any components that use `useGtag()`. If using SSR, ensure `useGtag` calls are within `onMounted` or `nextTick` hooks to guarantee browser context.
The requested module 'vue-gtag' does not provide an export named 'useGtag'.
Attempting to import `useGtag` (a named export) as a default export, or using CommonJS `require()` syntax in an ESM module.
fix
Always use `import { useGtag } from 'vue-gtag'` for the composable. For the main plugin, use `import VueGtag from 'vue-gtag'` (default export).
Google Analytics data is not appearing in reports.
Incorrect Google Analytics ID, misconfigured `vue-gtag` options, ad blockers, or consent settings preventing data transmission.
fix
Verify the `id` in `VueGtag` options matches your GA4 Measurement ID. Check browser console for `gtag.js` network errors. Inspect consent settings. Temporarily disable ad blockers for testing.
[Vue warn]: Failed to resolve plugin: VueGtag
The `VueGtag` plugin was not imported correctly, or `app.use()` received an `undefined` value instead of the plugin.
fix
Ensure `import VueGtag from 'vue-gtag'` is present and correct at the top of your `main.ts` (or equivalent entry file). Double-check for typos.
Upgrade
Version history
3.7.0latest on npm
Audit
Dependencies
vuerequiredCore Vue 3 framework dependency.
vue-routeroptionalOptional for automatic pageview tracking. If omitted, pageviews must be tracked manually.
Agent activity
37 hits · last 30 days
node
34
OpenAI (training)
1
Resources