Vue-gtag

Common errors

• TypeError: Cannot read properties of undefined (reading 'event')

  cause 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'.

  cause 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.

  cause 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

  cause 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.

Warnings

• breaking Vue-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.
• gotcha While `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 })`.
• gotcha Implementing 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.
• gotcha Ad 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.
• gotcha Vue 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.
• gotcha Ensure 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.

Install

• npm install vue-gtag npm
• yarn add vue-gtag yarn
• pnpm add vue-gtag pnpm

Imports

• VueGtag
  wrong:

  import { VueGtag } from 'vue-gtag'

  correct:

  import VueGtag from 'vue-gtag'

  VueGtag is the default export representing the Vue plugin for `app.use()`.
• useGtag
  wrong:

  import useGtag from 'vue-gtag'

  correct:

  import { useGtag } from 'vue-gtag'

  The `useGtag` composable provides reactive access to gtag functions within Vue components.
• GtagOptions
  wrong:

  import { GtagOptions } from 'vue-gtag'

  correct:

  import type { GtagOptions } from 'vue-gtag'

  Use `import type` for type-only imports to ensure proper tree-shaking and avoid runtime issues.

Quickstart

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>