0
# Plugin Configuration
1

2
Core plugin configuration functionality for adding PWA capabilities to VuePress sites with service worker generation, offline caching, and update notifications.
3

4
## Capabilities
5

6
### PWA Plugin Function
7

8
Main plugin factory function that configures VuePress with PWA functionality.
9

10
```javascript { .api }
11
/**
12
 * VuePress PWA Plugin
13
 * @param {PluginConfig4PWA} options - Plugin configuration options (default: {})
14
 * @param {VuePressContext} context - VuePress build context
15
 * @returns {VuePressPlugin} VuePress plugin object with PWA enhancements
16
 */
17
function pwaPlugin(options = {}, context): VuePressPlugin;
18

19
interface PluginConfig4PWA {
20
  /** Enable/disable service worker generation (default: true) */
21
  serviceWorker?: boolean;
22
  /** Enable update popup notifications (default: false) */
23
  updatePopup?: boolean | UpdatePopupConfig;
24
  /** Name of popup component to use (default: 'SWUpdatePopup') */
25
  popupComponent?: string;
26
  /** Configuration passed to workbox-build for service worker generation */
27
  generateSWConfig?: WorkboxConfig;
28
}
29

30
interface VuePressPlugin {
31
  /** Module aliases for internal components */
32
  alias: Record<string, string>;
33
  /** Function to define global constants */
34
  define: () => Record<string, any>;
35
  /** Global UI components to register */
36
  globalUIComponents?: string;
37
  /** Path to client-side app enhancement file */
38
  enhanceAppFiles: string;
39
  /** Hook called after site generation to create service worker */
40
  generated: () => Promise<void>;
41
}
42
```
43

44
**Usage Examples:**
45

46
```javascript
47
// .vuepress/config.js - Basic configuration with default popup
48
module.exports = {
49
  plugins: [
50
    ['@vuepress/pwa', {
51
      serviceWorker: true,
52
      updatePopup: true  // Uses default messages
53
    }]
54
  ]
55
}
56

57
// .vuepress/config.js - Custom popup messages
58
module.exports = {
59
  plugins: [
60
    ['@vuepress/pwa', {
61
      serviceWorker: true,
62
      updatePopup: {
63
        message: "New content is available.",
64
        buttonText: "Refresh"
65
      }
66
    }]
67
  ]
68
}
69

70
// Advanced configuration with custom options
71
module.exports = {
72
  plugins: [
73
    ['@vuepress/pwa', {
74
      serviceWorker: true,
75
      updatePopup: {
76
        message: "New content is available.",
77
        buttonText: "Refresh",
78
        '/zh/': {
79
          message: '发现新内容可用',
80
          buttonText: '刷新'
81
        }
82
      },
83
      popupComponent: 'CustomSWUpdatePopup',
84
      generateSWConfig: {
85
        globPatterns: [
86
          '**/*.{js,css,html,png,jpg,jpeg,gif,svg,woff,woff2,eot,ttf,otf}'
87
        ],
88
        runtimeCaching: [{
89
          urlPattern: /^https:\/\/fonts\.googleapis\.com\//,
90
          handler: 'StaleWhileRevalidate'
91
        }]
92
      }
93
    }]
94
  ]
95
}
96
```
97

98
### Update Popup Configuration
99

100
Configuration options for service worker update notifications. Can be a boolean to enable/disable with defaults, or an object for custom configuration.
101

102
```javascript { .api }
103
interface UpdatePopupConfig {
104
  /** Default update notification message (default: 'New content is available.') */
105
  message?: string;
106
  /** Default refresh button text (default: 'Refresh') */
107
  buttonText?: string;
108
  /** Localized messages for different routes */
109
  [locale: string]: {
110
    message: string;
111
    buttonText: string;
112
  };
113
}
114
```
115

116
Supported locales with default messages:
117

118
- `/` (English): "New content is available." / "Refresh"
119
- `/zh/` (Chinese): "发现新内容可用" / "刷新"  
120
- `/ru/` (Russian): "Доступен новый контент." / "Обновить"
121
- `/uk/` (Ukrainian): "Доступний новий контент." / "Оновити"
122
- `/ja/` (Japanese): "新しいコンテンツがあります。" / "更新する"
123
- `/es/` (Spanish): "Hay nuevo contenido disponible." / "Actualizar"
124

125
### Workbox Configuration
126

127
Configuration passed to workbox-build for service worker generation.
128

129
```javascript { .api }
130
interface WorkboxConfig {
131
  /** Destination path for generated service worker (auto-generated to outDir/service-worker.js) */
132
  swDest?: string;
133
  /** Directory to search for files to cache (defaults to VuePress outDir) */
134
  globDirectory?: string;
135
  /** Patterns matching files to cache (default: ['**/*.{js,css,html,png,jpg,jpeg,gif,svg,woff,woff2,eot,ttf,otf}']) */
136
  globPatterns?: string[];
137
  /** Maximum file size to include in precache (in bytes) */
138
  maximumFileSizeToCacheInBytes?: number;
139
  /** Runtime caching configuration for dynamic content */
140
  runtimeCaching?: RuntimeCachingEntry[];
141
  /** Skip waiting for service worker activation */
142
  skipWaiting?: boolean;
143
  /** Take control of clients immediately */
144
  clientsClaim?: boolean;
145
  /** Additional workbox-build configuration options */
146
  [key: string]: any;
147
}
148

149
interface RuntimeCachingEntry {
150
  /** URL pattern to match for caching */
151
  urlPattern: RegExp | string;
152
  /** Caching strategy to use */
153
  handler: 'CacheFirst' | 'NetworkFirst' | 'NetworkOnly' | 'CacheOnly' | 'StaleWhileRevalidate';
154
  /** Cache configuration options */
155
  options?: {
156
    cacheName?: string;
157
    expiration?: {
158
      maxEntries?: number;
159
      maxAgeSeconds?: number;
160
    };
161
  };
162
}
163
```
164

165
**Default caching patterns:**
166
- `**/*.{js,css,html,png,jpg,jpeg,gif,svg,woff,woff2,eot,ttf,otf}`
167

168
### Global Constants
169

170
Constants defined at build time and available in client code.
171

172
```javascript { .api }
173
interface GlobalConstants {
174
  /** Base URL for service worker registration (defaults to context.base || '/') */
175
  SW_BASE_URL: string;
176
  /** Boolean indicating if service worker is enabled (derived from !!serviceWorker) */
177
  SW_ENABLED: boolean;
178
  /** Update popup configuration (from plugin options) */
179
  SW_UPDATE_POPUP: boolean | UpdatePopupConfig;
180
  /** Name of popup component (from plugin options) */
181
  SW_POPUP_COMPONENT: string;
182
}
183
```
184

185
These constants are automatically injected and available in client-side code without imports.
186

187
## Types
188

189
```javascript { .api }
190
interface VuePressContext {
191
  /** Build output directory */
192
  outDir: string;
193
  /** Site base URL (default: '/') */
194
  base?: string;
195
}
196
```