0
# @nuxtjs/pwa
1

2
@nuxtjs/pwa is a comprehensive Progressive Web App solution for Nuxt.js applications providing zero-configuration PWA setup. It integrates service worker management through Workbox, web app manifest generation, meta tag optimization, and automatic icon generation to transform regular Nuxt.js applications into full-featured PWAs with offline support, installability, and performance optimizations.
3

4
## Package Information
5

6
- **Package Name**: @nuxtjs/pwa
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @nuxtjs/pwa`
10

11
## Core Imports
12

13
Since this is a Nuxt.js module, it's configured in the Nuxt configuration rather than imported directly:
14

15
```typescript
16
// nuxt.config.ts
17
export default {
18
  modules: ['@nuxtjs/pwa'],
19
  pwa: {
20
    // PWA configuration options
21
  }
22
}
23
```
24

25
For accessing generated runtime functionality:
26

27
```typescript
28
// In Vue components or plugins
29
this.$icon('192x192'); // Access generated icons
30
```
31

32
## Basic Usage
33

34
```typescript
35
// nuxt.config.ts
36
export default {
37
  modules: ['@nuxtjs/pwa'],
38
  pwa: {
39
    meta: {
40
      name: 'My PWA App',
41
      description: 'A progressive web application',
42
      theme_color: '#2196f3'
43
    },
44
    manifest: {
45
      name: 'My PWA App',
46
      short_name: 'PWA App',
47
      background_color: '#ffffff'
48
    },
49
    workbox: {
50
      offline: true,
51
      cacheAssets: true
52
    },
53
    icon: {
54
      sizes: [64, 120, 144, 152, 192, 384, 512]
55
    }
56
  }
57
}
58
```
59

60
## Architecture
61

62
@nuxtjs/pwa is structured around four main sub-modules:
63

64
- **PWA Module**: Main orchestrator that coordinates all sub-modules during Nuxt.js build process
65
- **Icon Module**: Handles automatic icon generation and resizing for different device requirements
66
- **Manifest Module**: Generates web app manifest files with PWA metadata and configuration
67
- **Meta Module**: Manages HTML meta tags for PWA compliance, SEO, and social media optimization
68
- **Workbox Module**: Integrates Workbox for service worker management, caching strategies, and offline functionality
69

70
## Capabilities
71

72
### PWA Module Configuration
73

74
Main module configuration interface for coordinating PWA setup across all sub-modules.
75

76
```typescript { .api }
77
interface PWAOptions {
78
  meta?: Partial<MetaOptions> | false;
79
  icon?: Partial<IconOptions> | false;
80
  workbox?: Partial<WorkboxOptions> | false;
81
  manifest?: Partial<ManifestOptions> | false;
82
}
83

84
/**
85
 * Main PWA module function that coordinates all sub-modules
86
 * @param moduleOptions - Configuration options for PWA sub-modules
87
 * @returns Promise that resolves when all modules are initialized
88
 */
89
export default async function pwa(moduleOptions: PWAOptions): Promise<void>;
90
```
91

92
[PWA Module](./pwa-module.md)
93

94
### Icon Generation
95

96
Automatic icon generation and resizing from a source image for various device sizes and iOS splash screens.
97

98
```typescript { .api }
99
interface IconOptions {
100
  source: string;
101
  fileName: string;
102
  sizes: number[];
103
  iosSizes: [number, number, string][];
104
  targetDir: string;
105
  plugin: boolean;
106
  pluginName: string;
107
  purpose: string[] | string;
108
  cacheDir: string;
109
  publicPath: string;
110
}
111
```
112

113
[Icon Generation](./icon-generation.md)
114

115
### Manifest Generation
116

117
Web app manifest generation with customizable PWA metadata and configuration options.
118

119
```typescript { .api }
120
interface ManifestOptions {
121
  name: string;
122
  short_name: string;
123
  description: string;
124
  icons: Record<string, any>[];
125
  start_url: string;
126
  display: string;
127
  background_color: string;
128
  theme_color: string;
129
  dir: 'ltr' | 'rtl';
130
  lang: string;
131
  useWebmanifestExtension: boolean;
132
  publicPath: string;
133
  fileName: string;
134
  crossorigin: boolean;
135
}
136
```
137

138
[Manifest Generation](./manifest-generation.md)
139

140
### Meta Tag Management
141

142
HTML meta tag generation for PWA compliance, SEO optimization, and social media integration.
143

144
```typescript { .api }
145
interface MetaOptions extends Partial<ManifestOptions> {
146
  charset: string;
147
  viewport: string;
148
  mobileApp: boolean;
149
  mobileAppIOS: boolean;
150
  appleStatusBarStyle: string;
151
  favicon: boolean;
152
  name: string;
153
  title?: string;
154
  author: string;
155
  description: string;
156
  theme_color: string;
157
  lang: string;
158
  ogType: string;
159
  ogSiteName: string | true;
160
  ogTitle: string | true;
161
  ogDescription: string | true;
162
  ogHost: string | undefined;
163
  ogImage: boolean | string | OgImageObject;
164
  ogUrl: string | undefined | true;
165
  twitterCard: string | undefined;
166
  twitterSite: string | undefined;
167
  twitterCreator: string | undefined;
168
  nativeUI: boolean;
169
}
170

171
interface OgImageObject {
172
  path?: string;
173
  width?: number;
174
  height?: number;
175
  type?: string;
176
}
177
```
178

179
[Meta Tag Management](./meta-tag-management.md)
180

181
### Service Worker & Caching
182

183
Workbox integration for service worker management, caching strategies, and offline functionality.
184

185
```typescript { .api }
186
interface WorkboxOptions {
187
  dev: boolean;
188
  workboxVersion: string;
189
  workboxURL: string;
190
  importScripts: string[];
191
  autoRegister: boolean;
192
  enabled: boolean;
193
  cacheNames: Record<string, any>;
194
  config: Record<string, any>;
195
  clientsClaim: boolean;
196
  skipWaiting: boolean;
197
  offlineAnalytics: boolean;
198
  workboxExtensions: string | string[];
199
  preCaching: string[] | {url: string, revision: string}[];
200
  cacheOptions: CacheOptions;
201
  cachingExtensions: string | string[];
202
  cleanupOutdatedCaches: boolean;
203
  offline: boolean;
204
  offlineStrategy: CachingStrategy;
205
  offlinePage: string;
206
  offlineAssets: string[];
207
  runtimeCaching: RuntimeCaching[];
208
  cacheAssets: boolean;
209
  routingExtensions: string | string[];
210
  assetsURLPattern: string;
211
  pagesURLPattern: string;
212
  swTemplate: string;
213
  swURL: string;
214
  swDest: string;
215
  swScope: string;
216
  routerBase: string;
217
  publicPath: string;
218
}
219

220
interface CacheOptions {
221
  cacheId: string;
222
  directoryIndex: string;
223
  revision: string | undefined;
224
}
225

226
interface RuntimeCaching {
227
  urlPattern: string;
228
  handler?: CachingStrategy;
229
  method?: HTTPMethod;
230
  strategyOptions?: StrategyOptions;
231
  strategyPlugins?: StrategyPlugin[];
232
}
233

234
type CachingStrategy = 'CacheFirst' | 'CacheOnly' | 'NetworkFirst' | 'NetworkOnly' | 'StaleWhileRevalidate';
235

236
type HTTPMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH';
237

238
interface StrategyOptions {
239
  cacheName?: string;
240
  plugins?: any[];
241
  networkTimeoutSeconds?: number;
242
  ignoreVary?: boolean;
243
  cacheKeyWillBeUsed?: boolean;
244
  cacheWillUpdate?: boolean;
245
  fetchDidSucceed?: boolean;
246
  requestWillFetch?: boolean;
247
}
248
```
249

250
[Service Worker & Caching](./service-worker-caching.md)
251

252
## Core Utilities
253

254
### URL Utilities
255

256
URL manipulation and path handling utilities used throughout the PWA module.
257

258
```typescript { .api }
259
/**
260
 * Check if a URL is absolute (starts with http/https or //)
261
 * @param url - URL string to check
262
 * @returns True if URL is absolute
263
 */
264
function isUrl(url: string): boolean;
265

266
/**
267
 * Join URL paths with proper handling of protocol separators
268
 * @param args - URL path segments to join
269
 * @returns Joined URL path
270
 */
271
function joinUrl(...args: string[]): string;
272

273
/**
274
 * Extract router base and public path from Nuxt options
275
 * @param options - Nuxt configuration options
276
 * @returns Object containing routerBase and publicPath
277
 */
278
function getRouteParams(options: any): { routerBase: string; publicPath: string };
279
```
280

281
### Size and String Utilities
282

283
Utilities for icon size normalization and string manipulation.
284

285
```typescript { .api }
286
/**
287
 * Normalize size array to ensure consistent [width, height] format
288
 * @param size - Size as number, array, or undefined
289
 * @returns Normalized [width, height] size array
290
 */
291
function normalizeSize(size: number | [number, number] | []): [number, number];
292

293
/**
294
 * Generate size name string from size array
295
 * @param size - Size array (supports third element for prefix)
296
 * @returns Size name in format "prefix_WxH" or "WxH"
297
 */
298
function sizeName(size: number | [number, number] | [number, number, string]): string;
299

300
/**
301
 * Convert string to start case (first letter uppercase)
302
 * @param str - String to convert
303
 * @returns String with first letter capitalized
304
 */
305
function startCase(str: string): string;
306
```
307

308
### File and Asset Utilities
309

310
File system and asset management utilities.
311

312
```typescript { .api }
313
/**
314
 * Emit asset to build directory during build process
315
 * @param nuxt - Nuxt instance
316
 * @param fileName - Target file name
317
 * @param data - File content or Promise that resolves to content
318
 */
319
function emitAsset(nuxt: any, fileName: string, data: string | Promise<string>): void;
320

321
/**
322
 * Write data to file with directory creation
323
 * @param path - Target file path
324
 * @param data - Data to write or Promise that resolves to data
325
 */
326
async function writeData(path: string, data: string | Promise<string>): Promise<void>;
327

328
/**
329
 * Read and concatenate JavaScript files
330
 * @param nuxt - Nuxt instance
331
 * @param files - File path or array of file paths
332
 * @returns Concatenated file contents
333
 */
334
async function readJSFiles(nuxt: any, files: string | string[]): Promise<string>;
335

336
/**
337
 * Copy template file with variable substitution
338
 * @param options - Template copy options
339
 */
340
async function copyTemplate(options: { src: string; dst: string; options: any }): Promise<void>;
341
```
342

343
### Object and Meta Utilities
344

345
Object manipulation and meta tag handling utilities.
346

347
```typescript { .api }
348
/**
349
 * Pick specific properties from an object
350
 * @param obj - Source object
351
 * @param props - Array of property names to pick
352
 * @returns New object with selected properties
353
 */
354
function pick(obj: Record<string, any>, props: string[]): Record<string, any>;
355

356
/**
357
 * Generate random string of specified length
358
 * @param length - Desired string length
359
 * @returns Random alphanumeric string
360
 */
361
function randomString(length: number): string;
362

363
/**
364
 * Merge meta object arrays with deduplication
365
 * @param to - Target meta object
366
 * @param from - Source meta object to merge
367
 */
368
function mergeMeta(to: Record<string, any>, from: Record<string, any>): void;
369
```
370

371
## Types
372

373
### Core Context Interface
374

375
```typescript { .api }
376
interface PWAContext {
377
  meta?: MetaOptions;
378
  icon?: IconOptions;
379
  workbox?: WorkboxOptions;
380
  manifest?: ManifestOptions;
381
  _manifestMeta: any;
382
}
383
```
384

385
### iOS Device Types
386

387
```typescript { .api }
388
type iOSType = 'ipad' | 'ipadpro9' | 'ipadpro10' | 'ipadpro12' | 'iphonese' | 'iphone6' | 'iphoneplus' | 'iphonex' | 'iphonexr' | 'iphonexsmax';
389

390
type iOSSize = [number, number, iOSType];
391
```
392

393
### Strategy Plugin Types
394

395
```typescript { .api }
396
type StrategyPlugin = BackgroundSync | BroadcastUpdate | CacheableResponse | Expiration | RangeRequests;
397

398
interface BackgroundSync {
399
  use: 'BackgroundSync';
400
  config: any;
401
}
402

403
interface BroadcastUpdate {
404
  use: 'BroadcastUpdate';
405
  config: any;
406
}
407

408
interface CacheableResponse {
409
  use: 'CacheableResponse';
410
  config: any;
411
}
412

413
interface Expiration {
414
  use: 'Expiration';
415
  config: any;
416
}
417

418
interface RangeRequests {
419
  use: 'RangeRequests';
420
  config: any;
421
}
422
```