0
# VuePress Google Analytics Plugin
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @vuepress/plugin-google-analytics
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @vuepress/plugin-google-analytics`
10

11
## Core Imports
12

13
```javascript
14
// Plugin is not imported directly, but configured in VuePress config
15
module.exports = {
16
  plugins: [
17
    ['@vuepress/plugin-google-analytics', {
18
      ga: 'UA-XXXXX-X' // Your tracking ID
19
    }]
20
  ]
21
}
22
```
23

24
## Basic Usage
25

26
```javascript
27
// .vuepress/config.js
28
module.exports = {
29
  plugins: [
30
    ['@vuepress/plugin-google-analytics', {
31
      ga: 'UA-XXXXX-X' // Universal Analytics tracking ID
32
    }]
33
  ]
34
}
35
```
36

37
Alternative configuration using site-level config:
38

39
```javascript
40
// .vuepress/config.js
41
module.exports = {
42
  ga: 'UA-XXXXX-X', // Site-level configuration
43
  plugins: [
44
    '@vuepress/plugin-google-analytics'
45
  ]
46
}
47
```
48

49
## Capabilities
50

51
### Plugin Factory Function
52

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

55
```javascript { .api }
56
/**
57
 * Creates a VuePress plugin instance for Google Analytics integration
58
 * @param {PluginOptions} options - Plugin configuration options (default: {})
59
 * @param {Context} context - VuePress context object
60
 * @returns {PluginObject} VuePress plugin object
61
 */
62
module.exports = (options = {}, context) => PluginObject;
63

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

69
interface Context {
70
  /** VuePress site configuration object */
71
  siteConfig?: {
72
    /** Alternative location for Google Analytics tracking ID */
73
    ga?: string;
74
  };
75
}
76

77
interface PluginObject {
78
  /** Function that defines variables available to client code */
79
  define(): { GA_ID: string | false };
80
  /** Path to client enhancement file for Google Analytics injection */
81
  enhanceAppFiles: string;
82
}
83
```
84

85
**Usage Pattern:**
86
- Plugin automatically detects production environment and only activates tracking in production builds
87
- Tracking ID can be provided via plugin options (`options.ga`) or site configuration (`siteConfig.ga`)
88
- Plugin options take precedence over site configuration
89
- If no tracking ID is provided, GA_ID will be `false` and tracking will be disabled
90

91
### Client Enhancement Function
92

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

95
```javascript { .api }
96
/**
97
 * Client-side enhancement function for Google Analytics integration
98
 * @param {EnhancementContext} context - Client enhancement context
99
 */
100
export default function clientEnhancement(context: EnhancementContext): void;
101

102
interface EnhancementContext {
103
  /** Vue Router instance for tracking navigation */
104
  router: VueRouter;
105
}
106

107
interface VueRouter {
108
  /** Hook that fires after each route navigation */
109
  afterEach(callback: (to: Route) => void): void;
110
  /** Current Vue app instance */
111
  app: {
112
    /** VuePress helper function for base path resolution */
113
    $withBase(path: string): string;
114
  };
115
}
116

117
interface Route {
118
  /** Full path of the current route */
119
  fullPath: string;
120
}
121
```
122

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

132
## Configuration Options
133

134
### Plugin Options
135

136
```javascript { .api }
137
interface PluginOptions {
138
  /** 
139
   * Google Analytics tracking ID
140
   * Supports both Universal Analytics (UA-XXXXX-X) and GA4 (G-XXXXXXXXXX) formats
141
   * Takes precedence over site-level configuration
142
   */
143
  ga?: string;
144
}
145
```
146

147
### Site Configuration
148

149
```javascript { .api }
150
interface SiteConfig {
151
  /**
152
   * Alternative location for Google Analytics tracking ID
153
   * Used when plugin is configured without explicit options
154
   * Plugin options take precedence over this setting
155
   */
156
  ga?: string;
157
}
158
```
159

160
## Implementation Details
161

162
### Tracking Features
163

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

170
### Security Considerations
171

172
- Script injection only occurs in production environment
173
- No tracking data is sent during development
174
- IP anonymization is enabled by default
175
- External script loading is controlled and secure
176

177
### Integration Points
178

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

184
## Error Handling
185

186
The plugin gracefully handles various edge cases:
187

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