0
# VuePress PWA Plugin
1

2
VuePress PWA Plugin (@vuepress/plugin-pwa) adds Progressive Web App functionality to VuePress sites by providing service worker generation, offline caching, and update notifications. It enables VuePress documentation sites to work offline and provide app-like experiences for users. The plugin is only active in production mode for performance and development workflow reasons.
3

4
## Package Information
5

6
- **Package Name**: @vuepress/plugin-pwa
7
- **Package Type**: npm (VuePress Plugin)
8
- **Language**: JavaScript
9
- **Installation**: `npm install @vuepress/plugin-pwa`
10
- **Dependencies**: register-service-worker ^1.7.0, workbox-build ^4.3.1
11

12
## Core Imports
13

14
```javascript
15
const pwaPlugin = require('@vuepress/plugin-pwa');
16
```
17

18
For VuePress configuration:
19

20
```javascript
21
// .vuepress/config.js
22
module.exports = {
23
  plugins: [
24
    ['@vuepress/pwa', {
25
      serviceWorker: true,
26
      updatePopup: true
27
    }]
28
  ]
29
}
30
```
31

32
## Basic Usage
33

34
```javascript
35
// .vuepress/config.js
36
module.exports = {
37
  plugins: [
38
    ['@vuepress/pwa', {
39
      serviceWorker: true,
40
      updatePopup: {
41
        message: "New content is available.",
42
        buttonText: "Refresh"
43
      },
44
      generateSWConfig: {
45
        globPatterns: [
46
          '**/*.{js,css,html,png,jpg,jpeg,gif,svg,woff,woff2,eot,ttf,otf}'
47
        ]
48
      }
49
    }]
50
  ]
51
}
52
```
53

54
## Architecture
55

56
The VuePress PWA Plugin is built around several key components:
57

58
- **Plugin Configuration**: Main plugin function that configures VuePress for PWA functionality
59
- **Service Worker Generation**: Uses Workbox to automatically generate service workers for offline caching
60
- **Client-Side Enhancement**: Registers service workers and handles PWA events in the browser
61
- **Update Notifications**: Provides user interface components for notifying users of updates
62
- **Event System**: Client-side event bus for managing service worker lifecycle events
63
- **Google Analytics Integration**: Automatic error reporting to Google Analytics when GA_ID is available
64

65
## Capabilities
66

67
### Plugin Configuration
68

69
Core plugin function that adds PWA functionality to VuePress sites with configurable options for service worker behavior and update notifications.
70

71
```javascript { .api }
72
/**
73
 * VuePress PWA Plugin
74
 * @param {PluginConfig4PWA} options - Plugin configuration options (default: {})
75
 * @param {VuePressContext} context - VuePress build context
76
 * @returns {VuePressPlugin} VuePress plugin object
77
 */
78
function pwaPlugin(options, context): VuePressPlugin;
79

80
interface PluginConfig4PWA {
81
  /** Enable/disable service worker generation (default: true) */
82
  serviceWorker?: boolean;
83
  /** Enable update popup notifications (default: false) */
84
  updatePopup?: boolean | UpdatePopupConfig;
85
  /** Name of popup component to use (default: 'SWUpdatePopup') */
86
  popupComponent?: string;
87
  /** Configuration passed to workbox-build for service worker generation */
88
  generateSWConfig?: WorkboxConfig;
89
}
90

91
interface UpdatePopupConfig {
92
  /** Update notification message (default: 'New content is available.') */
93
  message?: string;
94
  /** Refresh button text (default: 'Refresh') */
95
  buttonText?: string;
96
  /** Localized messages for different routes */
97
  [locale: string]: {
98
    message: string;
99
    buttonText: string;
100
  };
101
}
102

103
interface VuePressPlugin {
104
  alias: Record<string, string>;
105
  define: () => Record<string, any>;
106
  globalUIComponents?: string;
107
  enhanceAppFiles: string;
108
  generated: () => Promise<void>;
109
}
110
```
111

112
[Plugin Configuration](./plugin-configuration.md)
113

114
### Service Worker Events
115

116
Client-side service worker event handling and update management for PWA functionality.
117

118
```javascript { .api }
119
class SWUpdateEvent {
120
  constructor(registration: ServiceWorkerRegistration);
121
  /** Check if the new service worker exists or not */
122
  update(): Promise<ServiceWorkerRegistration>;
123
  /** Activate new service worker to work with new data */
124
  skipWaiting(): Promise<any>;
125
}
126
```
127

128
[Service Worker Events](./service-worker-events.md)
129

130
### Update Notifications
131

132
Vue component system for displaying service worker update notifications to users.
133

134
```javascript { .api }
135
// Global event bus for service worker events
136
const swEventBus: Vue;
137

138
// Default popup component
139
const SWUpdatePopup: VueComponent;
140

141
interface SWUpdatePopupProps {
142
  enabled: boolean;
143
  message: string;
144
  buttonText: string;
145
  reload: () => void;
146
}
147
```
148

149
[Update Notifications](./update-notifications.md)
150

151
## Types
152

153
```javascript { .api }
154
interface ServiceWorkerRegistration {
155
  update(): Promise<ServiceWorkerRegistration>;
156
  waiting?: ServiceWorker;
157
}
158

159
interface WorkboxConfig {
160
  /** Destination path for generated service worker (auto-generated to outDir/service-worker.js) */
161
  swDest?: string;
162
  /** Directory to search for files to cache (defaults to VuePress outDir) */
163
  globDirectory?: string;
164
  /** Patterns matching files to cache (default: ['**/*.{js,css,html,png,jpg,jpeg,gif,svg,woff,woff2,eot,ttf,otf}']) */
165
  globPatterns?: string[];
166
  /** Maximum file size to include in precache (in bytes) */
167
  maximumFileSizeToCacheInBytes?: number;
168
  /** Runtime caching configuration for dynamic content */
169
  runtimeCaching?: RuntimeCachingEntry[];
170
  /** Skip waiting for service worker activation */
171
  skipWaiting?: boolean;
172
  /** Take control of clients immediately */
173
  clientsClaim?: boolean;
174
  /** Additional workbox-build configuration options */
175
  [key: string]: any;
176
}
177

178
interface RuntimeCachingEntry {
179
  /** URL pattern to match for caching */
180
  urlPattern: RegExp | string;
181
  /** Caching strategy to use */
182
  handler: 'CacheFirst' | 'NetworkFirst' | 'NetworkOnly' | 'CacheOnly' | 'StaleWhileRevalidate';
183
  /** Cache configuration options */
184
  options?: {
185
    cacheName?: string;
186
    expiration?: {
187
      maxEntries?: number;
188
      maxAgeSeconds?: number;
189
    };
190
  };
191
}
192

193
interface VuePressContext {
194
  /** Build output directory */
195
  outDir: string;
196
  /** Site base URL */
197
  base?: string;
198
}
199
```