0
# Plugin Configuration
1

2
Configuration options and setup for the Vite Plugin PWA, including service worker strategies, manifest options, and development settings.
3

4
## Capabilities
5

6
### Main Plugin Function
7

8
Creates the Vite Plugin PWA with specified configuration options.
9

10
```typescript { .api }
11
/**
12
 * Creates a Vite Plugin PWA with the specified configuration
13
 * @param userOptions - Partial PWA configuration options
14
 * @returns Array of Vite plugins for PWA functionality
15
 */
16
function VitePWA(userOptions?: Partial<VitePWAOptions>): Plugin[];
17
```
18

19
**Usage Example:**
20

21
```typescript
22
import { VitePWA } from "vite-plugin-pwa";
23

24
// Basic configuration
25
const pwaPlugin = VitePWA({
26
  registerType: "autoUpdate",
27
  workbox: {
28
    globPatterns: ["**/*.{js,css,html,ico,png,svg}"],
29
  },
30
});
31

32
// Advanced configuration with custom service worker
33
const advancedPwaPlugin = VitePWA({
34
  strategies: "injectManifest",
35
  srcDir: "src",
36
  filename: "my-sw.ts",
37
  injectManifest: {
38
    swSrc: "src/my-sw.ts",
39
    swDest: "dist/my-sw.js", 
40
  },
41
  manifest: {
42
    name: "My Advanced PWA",
43
    short_name: "AdvancedPWA",
44
    icons: [
45
      {
46
        src: "icon-192.png",
47
        sizes: "192x192",
48
        type: "image/png",
49
      },
50
    ],
51
  },
52
});
53
```
54

55
### Service Worker Strategies
56

57
Configure how the service worker is generated and managed.
58

59
```typescript { .api }
60
type ServiceWorkerStrategy = 'generateSW' | 'injectManifest';
61

62
interface GenerateSWConfig {
63
  strategies: 'generateSW';
64
  workbox: Partial<GenerateSWOptions>;
65
}
66

67
interface InjectManifestConfig {
68
  strategies: 'injectManifest';
69
  injectManifest: Partial<CustomInjectManifestOptions>;
70
}
71
```
72

73
**generateSW Strategy:**
74

75
```typescript
76
VitePWA({
77
  strategies: "generateSW", // default
78
  workbox: {
79
    globPatterns: ["**/*.{js,css,html,ico,png,svg}"],
80
    runtimeCaching: cachePreset, // Use built-in cache preset
81
    cleanupOutdatedCaches: true,
82
    skipWaiting: true,
83
    clientsClaim: true,
84
  },
85
});
86
```
87

88
**injectManifest Strategy:**
89

90
```typescript
91
VitePWA({
92
  strategies: "injectManifest",
93
  srcDir: "src",
94
  filename: "custom-sw.ts",
95
  injectManifest: {
96
    swSrc: "src/custom-sw.ts",
97
    swDest: "dist/custom-sw.js",
98
    rollupFormat: "es",
99
    minify: true,
100
    sourcemap: true,
101
  },
102
});
103
```
104

105
### Registration Configuration
106

107
Control how the service worker is registered in the client application.
108

109
```typescript { .api }
110
type RegisterType = 'prompt' | 'autoUpdate';
111
type InjectRegister = 'inline' | 'script' | 'script-defer' | 'auto' | null | false;
112

113
interface RegistrationOptions {
114
  registerType?: RegisterType;
115
  injectRegister?: InjectRegister;
116
  scope?: string;
117
  immediate?: boolean;
118
}
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
// Auto-update mode - automatically updates when new SW is available
125
VitePWA({
126
  registerType: "autoUpdate",
127
  injectRegister: "auto", // default
128
});
129

130
// Prompt mode - user confirmation required for updates
131
VitePWA({
132
  registerType: "prompt", // default
133
  injectRegister: "script-defer", // deferred script injection
134
});
135

136
// Manual registration - no automatic injection
137
VitePWA({
138
  injectRegister: false, // Use virtual modules for manual control
139
});
140
```
141

142
### Web App Manifest Configuration
143

144
Configure the PWA manifest file for app metadata and display options.
145

146
```typescript { .api }
147
interface ManifestOptions {
148
  name: string;
149
  short_name: string;
150
  description?: string;
151
  icons: IconResource[];
152
  start_url?: string;
153
  scope?: string;
154
  id?: string;
155
  display?: Display;
156
  display_override?: DisplayOverride[];
157
  orientation?: 'any' | 'natural' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'portrait' | 'portrait-primary' | 'portrait-secondary';
158
  theme_color?: string;
159
  background_color?: string;
160
  lang?: string;
161
  dir?: 'ltr' | 'rtl';
162
  categories?: string[];
163
  screenshots?: ScreenshotResource[];
164
  shortcuts?: ShortcutResource[];
165
  related_applications?: RelatedApplication[];
166
  prefer_related_applications?: boolean;
167
  protocol_handlers?: ProtocolHandler[];
168
  file_handlers?: FileHandler[];
169
  share_target?: ShareTarget;
170
  handle_links?: 'auto' | 'preferred' | 'not-preferred';
171
  launch_handler?: LaunchHandler;
172
  edge_side_panel?: EdgeSidePanel;
173
  scope_extensions?: ScopeExtension[];
174
}
175

176
interface IconResource {
177
  src: string;
178
  sizes?: string;
179
  type?: string;
180
  purpose?: StringLiteralUnion<IconPurpose> | IconPurpose[];
181
}
182

183
type Display = 'fullscreen' | 'standalone' | 'minimal-ui' | 'browser';
184
type DisplayOverride = Display | 'window-controls-overlay';
185
type IconPurpose = 'monochrome' | 'maskable' | 'any';
186
```
187

188
**Usage Example:**
189

190
```typescript
191
VitePWA({
192
  manifest: {
193
    name: "My Progressive Web App",
194
    short_name: "MyPWA",
195
    description: "A comprehensive PWA built with Vite",
196
    theme_color: "#ffffff",
197
    background_color: "#ffffff",
198
    display: "standalone",
199
    orientation: "portrait",
200
    scope: "/",
201
    start_url: "/",
202
    icons: [
203
      {
204
        src: "pwa-64x64.png",
205
        sizes: "64x64",
206
        type: "image/png",
207
      },
208
      {
209
        src: "pwa-192x192.png",
210
        sizes: "192x192",
211
        type: "image/png",
212
      },
213
      {
214
        src: "pwa-512x512.png",
215
        sizes: "512x512",
216
        type: "image/png",
217
        purpose: "any",
218
      },
219
      {
220
        src: "maskable-icon-512x512.png",
221
        sizes: "512x512",
222
        type: "image/png",
223
        purpose: "maskable",
224
      },
225
    ],
226
    screenshots: [
227
      {
228
        src: "screenshot-wide.png",
229
        sizes: "1280x720",
230
        type: "image/png",
231
        form_factor: "wide",
232
      },
233
    ],
234
    shortcuts: [
235
      {
236
        name: "Dashboard",
237
        short_name: "Dashboard",
238
        description: "View the dashboard",
239
        url: "/dashboard",
240
        icons: [{ src: "dashboard-icon.png", sizes: "192x192" }],
241
      },
242
    ],
243
  },
244
});
245
```
246

247
### Development Options
248

249
Configure PWA behavior during development.
250

251
```typescript { .api }
252
interface DevOptions {
253
  enabled?: boolean;
254
  suppressWarnings?: boolean;
255
  navigateFallback?: string;
256
  navigateFallbackAllowlist?: RegExp[];
257
  navigateFallbackDenylist?: RegExp[];
258
  type?: 'classic' | 'module';
259
  webManifestUrl?: string;
260
}
261
```
262

263
**Usage Example:**
264

265
```typescript
266
VitePWA({
267
  devOptions: {
268
    enabled: true, // Enable PWA in development
269
    suppressWarnings: true,
270
    navigateFallback: "index.html",
271
    type: "module",
272
  },
273
});
274
```
275

276
### PWA Assets Generation
277

278
Configure automatic generation of PWA icons and splash screens.
279

280
```typescript { .api }
281
interface PWAAssetsOptions {
282
  disabled?: boolean;
283
  config?: string | boolean;
284
  preset?: false | BuiltInPreset | Preset;
285
  image?: string;
286
  htmlPreset?: HtmlLinkPreset;
287
  includeHtmlHeadLinks?: boolean;
288
  overrideManifestIcons?: boolean;
289
  injectThemeColor?: boolean;
290
  integration?: PWAAssetsIntegration;
291
}
292

293
interface PWAAssetsIntegration {
294
  baseUrl?: string;
295
  publicDir?: string;
296
  outDir?: string;
297
}
298
```
299

300
**Usage Example:**
301

302
```typescript
303
VitePWA({
304
  pwaAssets: {
305
    preset: "minimal-2023",
306
    image: "public/logo.svg",
307
    htmlPreset: "2023",
308
    includeHtmlHeadLinks: true,
309
    overrideManifestIcons: false,
310
    injectThemeColor: true,
311
  },
312
});
313
```
314

315
### Integration Hooks
316

317
Provide custom integration hooks for advanced use cases.
318

319
```typescript { .api }
320
interface PWAIntegration {
321
  beforeBuildServiceWorker?: (options: ResolvedVitePWAOptions) => void | Promise<void>;
322
  closeBundleOrder?: 'pre' | 'post' | null;
323
  configureOptions?: (viteOptions: ResolvedConfig, options: Partial<VitePWAOptions>) => void | Promise<void>;
324
  configureCustomSWViteBuild?: (options: InlineConfig) => void | Promise<void>;
325
}
326
```
327

328
## Constants
329

330
### Cache Preset
331

332
Pre-configured runtime caching strategies for common asset types.
333

334
```typescript { .api }
335
const cachePreset: RuntimeCaching[];
336
```
337

338
The cache preset includes optimized caching strategies for:
339

340
- Google Fonts (CacheFirst, 365 days)
341
- Font files (StaleWhileRevalidate, 7 days)
342
- Images (StaleWhileRevalidate, 24 hours)
343
- JavaScript files (StaleWhileRevalidate, 24 hours)
344
- CSS files (StaleWhileRevalidate, 24 hours)
345
- JSON/XML/CSV data (NetworkFirst, 24 hours)
346
- API calls (NetworkFirst, 24 hours, 10s timeout)
347
- Other resources (NetworkFirst, 24 hours, 10s timeout)
348

349
### Default Inject Manifest Vite Plugins
350

351
Default list of Vite plugin IDs used when building custom service workers with injectManifest strategy.
352

353
```typescript { .api }
354
const defaultInjectManifestVitePlugins: string[];
355
```
356

357
Includes plugins: alias, commonjs, vite:resolve, vite:esbuild, replace, vite:define, rollup-plugin-dynamic-import-variables, vite:esbuild-transpile, vite:json, vite:terser.