VuePress Google Analytics Plugin

The VuePress Google Analytics plugin provides seamless Google Analytics integration for VuePress documentation sites. It automatically injects tracking code during production builds, enables automatic page view tracking for single-page application navigation, and provides anonymized IP tracking for privacy compliance.

Package Information

• Package Name: @vuepress/plugin-google-analytics
• Package Type: npm
• Language: JavaScript
• Installation: npm install @vuepress/plugin-google-analytics

Core Imports

// Plugin is not imported directly, but configured in VuePress config
module.exports = {
  plugins: [
    ['@vuepress/plugin-google-analytics', {
      ga: 'UA-XXXXX-X' // Your tracking ID
    }]
  ]
}

Basic Usage

// .vuepress/config.js
module.exports = {
  plugins: [
    ['@vuepress/plugin-google-analytics', {
      ga: 'UA-XXXXX-X' // Universal Analytics tracking ID
    }]
  ]
}

Alternative configuration using site-level config:

// .vuepress/config.js
module.exports = {
  ga: 'UA-XXXXX-X', // Site-level configuration
  plugins: [
    '@vuepress/plugin-google-analytics'
  ]
}

Capabilities

Plugin Factory Function

The main plugin factory function that creates a VuePress plugin instance with Google Analytics integration.

/**
 * Creates a VuePress plugin instance for Google Analytics integration
 * @param {PluginOptions} options - Plugin configuration options (default: {})
 * @param {Context} context - VuePress context object
 * @returns {PluginObject} VuePress plugin object
 */
module.exports = (options = {}, context) => PluginObject;

interface PluginOptions {
  /** Google Analytics tracking ID (e.g., 'UA-XXXXX-X' or 'G-XXXXXXXXXX') */
  ga?: string;
}

interface Context {
  /** VuePress site configuration object */
  siteConfig?: {
    /** Alternative location for Google Analytics tracking ID */
    ga?: string;
  };
}

interface PluginObject {
  /** Function that defines variables available to client code */
  define(): { GA_ID: string | false };
  /** Path to client enhancement file for Google Analytics injection */
  enhanceAppFiles: string;
}

Usage Pattern:

• Plugin automatically detects production environment and only activates tracking in production builds
• Tracking ID can be provided via plugin options (options.ga) or site configuration (siteConfig.ga)
• Plugin options take precedence over site configuration
• If no tracking ID is provided, GA_ID will be false and tracking will be disabled

Client Enhancement Function

The client-side enhancement function that injects Google Analytics tracking code and sets up automatic page view tracking.

/**
 * Client-side enhancement function for Google Analytics integration
 * @param {EnhancementContext} context - Client enhancement context
 */
export default function clientEnhancement(context: EnhancementContext): void;

interface EnhancementContext {
  /** Vue Router instance for tracking navigation */
  router: VueRouter;
}

interface VueRouter {
  /** Hook that fires after each route navigation */
  afterEach(callback: (to: Route) => void): void;
  /** Current Vue app instance */
  app: {
    /** VuePress helper function for base path resolution */
    $withBase(path: string): string;
  };
}

interface Route {
  /** Full path of the current route */
  fullPath: string;
}

Behavior:

• Only executes in production environment (process.env.NODE_ENV === 'production')
• Only activates when GA_ID is available and browser environment is detected
• Loads Google Analytics Universal Analytics library (analytics.js)
• Initializes tracking with the provided GA_ID
• Enables IP anonymization (anonymizeIp: true) for privacy compliance
• Sets up automatic page view tracking on Vue Router navigation changes
• Uses VuePress's $withBase helper to resolve proper base paths for tracking

Configuration Options

Plugin Options

interface PluginOptions {
  /** 
   * Google Analytics tracking ID
   * Supports both Universal Analytics (UA-XXXXX-X) and GA4 (G-XXXXXXXXXX) formats
   * Takes precedence over site-level configuration
   */
  ga?: string;
}

Site Configuration

interface SiteConfig {
  /**
   * Alternative location for Google Analytics tracking ID
   * Used when plugin is configured without explicit options
   * Plugin options take precedence over this setting
   */
  ga?: string;
}

Implementation Details

Tracking Features

• Automatic Page View Tracking: Sends pageview events on Vue Router navigation
• IP Anonymization: Automatically enabled for privacy compliance
• Production-Only: Tracking only activates in production builds
• Universal Analytics: Uses Google Analytics Universal Analytics library
• Base Path Support: Properly handles VuePress base path configurations

Security Considerations

• Script injection only occurs in production environment
• No tracking data is sent during development
• IP anonymization is enabled by default
• External script loading is controlled and secure

Integration Points

• VuePress Plugin System: Follows standard VuePress plugin architecture
• Vue Router Integration: Hooks into router lifecycle for SPA tracking
• Build System: Integrates with VuePress build process for production activation
• Configuration System: Works with both plugin-level and site-level configuration

Error Handling

The plugin gracefully handles various edge cases:

• Missing Tracking ID: Plugin becomes inactive if no GA ID is provided
• Development Environment: No tracking occurs during development
• Server-Side Rendering: Client-side code only executes in browser environment
• Script Loading Failures: Google Analytics script loading is handled asynchronously
• Route Navigation Errors: Router hook failures don't affect site functionality