0
# @vue/cli-plugin-pwa
1

2
@vue/cli-plugin-pwa is a Vue CLI plugin that transforms Vue.js applications into Progressive Web Apps (PWAs) by integrating Workbox service workers, generating PWA manifest files, and injecting essential PWA meta tags. It provides comprehensive PWA configuration through webpack plugin integration and development middleware.
3

4
## Package Information
5

6
- **Package Name**: @vue/cli-plugin-pwa
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `vue add pwa`
10

11
## Core Imports
12

13
```javascript
14
// Main plugin function (Vue CLI plugin registration)
15
module.exports = require('@vue/cli-plugin-pwa');
16
```
17

18
For accessing individual components:
19

20
```javascript
21
const HtmlPwaPlugin = require('@vue/cli-plugin-pwa/lib/HtmlPwaPlugin');
22
const createNoopServiceWorkerMiddleware = require('@vue/cli-plugin-pwa/lib/noopServiceWorkerMiddleware');
23
const pwaUIConfig = require('@vue/cli-plugin-pwa/ui');
24
```
25

26
## Basic Usage
27

28
```javascript
29
// vue.config.js
30
module.exports = {
31
  pwa: {
32
    name: 'My PWA App',
33
    themeColor: '#4DBA87',
34
    msTileColor: '#000000',
35
    appleMobileWebAppCapable: 'yes',
36
    appleMobileWebAppStatusBarStyle: 'black',
37
    workboxPluginMode: 'GenerateSW',
38
    workboxOptions: {
39
      skipWaiting: true,
40
      clientsClaim: true
41
    },
42
    manifestOptions: {
43
      background_color: '#ffffff'
44
    }
45
  }
46
}
47
```
48

49
## Architecture
50

51
The plugin is built around several key components:
52

53
- **Plugin Function**: Main Vue CLI plugin that configures webpack and development server
54
- **HtmlPwaPlugin**: Webpack plugin that injects PWA meta tags and manifest links into HTML
55
- **Service Worker Management**: Production service worker generation via Workbox and development no-op middleware
56
- **Generator**: File template system for adding PWA files to projects during installation
57
- **UI Configuration**: Vue CLI UI integration for visual PWA configuration management
58

59
## Capabilities
60

61
### Main Plugin Configuration
62

63
Core Vue CLI plugin function that configures webpack with PWA capabilities and sets up development middleware.
64

65
```javascript { .api }
66
/**
67
 * Main Vue CLI plugin function
68
 * @param {Object} api - Vue CLI plugin API
69
 * @param {Object} options - Plugin configuration options
70
 */
71
function vuePwaPlugin(api, options);
72

73
interface PWAOptions {
74
  workboxPluginMode?: 'GenerateSW' | 'InjectManifest';
75
  workboxOptions?: WorkboxOptions;
76
  name?: string;
77
  themeColor?: string;
78
  msTileColor?: string;
79
  appleMobileWebAppCapable?: string;
80
  appleMobileWebAppStatusBarStyle?: string;
81
  assetsVersion?: string;
82
  manifestPath?: string;
83
  manifestOptions?: ManifestOptions;
84
  manifestCrossorigin?: string;
85
  iconPaths?: IconPaths;
86
}
87
```
88

89
[Plugin Configuration](./plugin-configuration.md)
90

91
### HTML PWA Integration
92

93
Webpack plugin that injects PWA-specific HTML meta tags, icons, and manifest links during build process.
94

95
```javascript { .api }
96
class HtmlPwaPlugin {
97
  constructor(options?: HtmlPwaOptions);
98
  apply(compiler: Compiler): void;
99
}
100

101
interface HtmlPwaOptions {
102
  name?: string;
103
  themeColor?: string;
104
  msTileColor?: string;
105
  appleMobileWebAppCapable?: string;
106
  appleMobileWebAppStatusBarStyle?: string;
107
  assetsVersion?: string;
108
  manifestPath?: string;
109
  manifestOptions?: ManifestOptions;
110
  manifestCrossorigin?: string;
111
  iconPaths?: IconPaths;
112
}
113
```
114

115
[HTML Integration](./html-integration.md)
116

117
### Service Worker Management
118

119
Service worker generation for production builds using Workbox, and development middleware serving no-op service workers.
120

121
```javascript { .api }
122
/**
123
 * Creates development middleware for no-op service worker
124
 * @returns {Function} Express middleware function
125
 */
126
function createNoopServiceWorkerMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
127
```
128

129
[Service Worker Management](./service-worker.md)
130

131
### Project Generation
132

133
Vue CLI generator function that sets up PWA files and dependencies during plugin installation.
134

135
```javascript { .api }
136
/**
137
 * Vue CLI generator function for PWA plugin installation
138
 * @param {Object} api - Vue CLI generator API
139
 */
140
function pwaGenerator(api: GeneratorAPI): void;
141
```
142

143
[Project Generation](./project-generation.md)
144

145
### UI Configuration
146

147
Vue CLI UI integration providing visual PWA configuration management interface.
148

149
```javascript { .api }
150
/**
151
 * Vue CLI UI configuration function for PWA plugin visual interface
152
 * @param {Object} api - Vue CLI UI API
153
 */
154
function pwaUIConfig(api: UIConfigAPI): void;
155
```
156

157
The UI configuration provides visual management for PWA settings through the Vue CLI GUI, including form prompts for all PWA options and file watchers for configuration changes.
158

159
## Types
160

161
```javascript { .api }
162
interface IconPaths {
163
  faviconSVG?: string;
164
  favicon32?: string;
165
  favicon16?: string;
166
  appleTouchIcon?: string;
167
  maskIcon?: string;
168
  msTileImage?: string;
169
}
170

171
interface ManifestOptions {
172
  name?: string;
173
  short_name?: string;
174
  start_url?: string;
175
  display?: string;
176
  background_color?: string;
177
  theme_color?: string;
178
  icons?: ManifestIcon[];
179
}
180

181
interface ManifestIcon {
182
  src: string;
183
  sizes: string;
184
  type: string;
185
  purpose?: string;
186
}
187

188
interface WorkboxOptions {
189
  exclude?: RegExp[];
190
  cacheId?: string;
191
  swSrc?: string;
192
  skipWaiting?: boolean;
193
  clientsClaim?: boolean;
194
}
195

196
// Vue CLI and Webpack API types
197
interface GeneratorAPI {
198
  extendPackage(packageChanges: object): void;
199
  injectImports(file: string, imports: string): void;
200
  render(templatePath: string): void;
201
  entryFile: string;
202
  invoking: boolean;
203
  hasPlugin(pluginName: string): boolean;
204
}
205

206
interface UIConfigAPI {
207
  describeConfig(config: object): void;
208
  addSuggestion(suggestion: object): void;
209
  removeSuggestion(id: string): void;
210
  onViewOpen(handler: Function): void;
211
  onConfigRead(handler: Function): void;
212
}
213

214
interface Compiler {
215
  hooks: {
216
    compilation: {
217
      tap(id: string, callback: Function): void;
218
    };
219
  };
220
  options: {
221
    output: {
222
      publicPath: string;
223
    };
224
  };
225
}
226

227
// Express types for middleware
228
interface Request {
229
  url: string;
230
}
231

232
interface Response {
233
  setHeader(name: string, value: string): void;
234
  send(data: string): void;
235
}
236

237
interface NextFunction {
238
  (): void;
239
}
240
```