0
# Vite Plugin PWA
1

2
Vite Plugin PWA is a zero-configuration Progressive Web App (PWA) plugin for Vite that provides comprehensive PWA support including automatic service worker generation, web app manifest injection, and framework integrations. It offers offline functionality via Workbox, built-in framework support for React, Vue, Svelte, SolidJS, and Preact, and PWA assets generation for icons and splash screens.
3

4
## Package Information
5

6
- **Package Name**: vite-plugin-pwa
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vite-plugin-pwa`
10

11
## Core Imports
12

13
```typescript
14
import { VitePWA } from "vite-plugin-pwa";
15
```
16

17
For cache presets and constants:
18

19
```typescript
20
import { VitePWA, cachePreset, defaultInjectManifestVitePlugins } from "vite-plugin-pwa";
21
```
22

23
For TypeScript types:
24

25
```typescript
26
import type { VitePWAOptions, ManifestOptions, RegisterSWOptions } from "vite-plugin-pwa";
27
```
28

29
## Basic Usage
30

31
```typescript
32
// vite.config.ts
33
import { defineConfig } from "vite";
34
import { VitePWA } from "vite-plugin-pwa";
35

36
export default defineConfig({
37
  plugins: [
38
    VitePWA({
39
      registerType: "autoUpdate",
40
      workbox: {
41
        globPatterns: ["**/*.{js,css,html,ico,png,svg}"],
42
      },
43
      manifest: {
44
        name: "My PWA App",
45
        short_name: "PWA App",
46
        description: "My Progressive Web Application",
47
        theme_color: "#ffffff",
48
        icons: [
49
          {
50
            src: "pwa-192x192.png",
51
            sizes: "192x192",
52
            type: "image/png",
53
          },
54
          {
55
            src: "pwa-512x512.png",
56
            sizes: "512x512",
57
            type: "image/png",
58
          },
59
        ],
60
      },
61
    }),
62
  ],
63
});
64
```
65

66
## Architecture
67

68
Vite Plugin PWA is built around several key components:
69

70
- **Plugin System**: Main `VitePWA` function returns array of Vite plugins (MainPlugin, InfoPlugin, BuildPlugin, DevPlugin, AssetsPlugin)
71
- **Service Worker Strategies**: Two approaches - `generateSW` (automatic) and `injectManifest` (custom)
72
- **Virtual Modules**: Framework-specific registration modules for seamless integration
73
- **Workbox Integration**: Built on Google's Workbox for service worker generation and caching strategies
74
- **Assets Generation**: Optional PWA icon and splash screen generation from source images
75
- **Development Support**: Dev server integration with service worker simulation
76

77
## Capabilities
78

79
### Plugin Configuration
80

81
Main plugin factory function and configuration options for setting up PWA functionality in Vite applications.
82

83
```typescript { .api }
84
function VitePWA(userOptions?: Partial<VitePWAOptions>): Plugin[];
85
```
86

87
[Plugin Configuration](./plugin-configuration.md)
88

89
### Virtual Module Registration
90

91
Framework-specific service worker registration modules that provide reactive integration with React, Vue, Svelte, SolidJS, and Preact applications.
92

93
```typescript { .api }
94
// Virtual module: virtual:pwa-register
95
function registerSW(options?: RegisterSWOptions): (reloadPage?: boolean) => Promise<void>;
96

97
// Framework-specific virtual modules return reactive state
98
function useRegisterSW(options?: RegisterSWOptions): {
99
  needRefresh: ReactiveState<boolean>;
100
  offlineReady: ReactiveState<boolean>;
101
  updateServiceWorker: (reloadPage?: boolean) => Promise<void>;
102
};
103
```
104

105
[Virtual Module Registration](./virtual-modules.md)
106

107
### PWA Information and Assets
108

109
Virtual modules providing access to PWA information and generated assets for integrations and custom implementations.
110

111
```typescript { .api }
112
// Virtual module: virtual:pwa-info
113
const pwaInfo: PwaInfo | undefined;
114

115
// Virtual module: virtual:pwa-assets/head
116
const pwaAssetsHead: PWAAssetsHead;
117

118
// Virtual module: virtual:pwa-assets/icons
119
const pwaAssetsIcons: PWAAssetsIcons;
120
```
121

122
[PWA Information and Assets](./pwa-info-assets.md)
123

124
## Core Types
125

126
```typescript { .api }
127
interface VitePWAOptions {
128
  /** Build mode @default process.env.NODE_ENV or "production" */
129
  mode?: 'development' | 'production';
130
  /** @default 'public' */
131
  srcDir?: string;
132
  /** @default 'dist' */
133
  outDir?: string;
134
  /** @default 'sw.js' */
135
  filename?: string;
136
  /** @default 'manifest.webmanifest' */
137
  manifestFilename?: string;
138
  /** @default 'generateSW' */
139
  strategies?: 'generateSW' | 'injectManifest';
140
  /** The scope to register the Service Worker @default same as base of Vite's config */
141
  scope?: string;
142
  /** Service worker registration method @default 'auto' */
143
  injectRegister?: 'inline' | 'script' | 'script-defer' | 'auto' | null | false;
144
  /** Mode for the virtual register @default 'prompt' */
145
  registerType?: 'prompt' | 'autoUpdate';
146
  /** Minify the generated manifest @default true */
147
  minify?: boolean;
148
  /** The manifest object */
149
  manifest?: Partial<ManifestOptions> | false;
150
  /** Whether to add crossorigin="use-credentials" to manifest link @default false */
151
  useCredentials?: boolean;
152
  /** The workbox object for generateSW */
153
  workbox?: Partial<GenerateSWOptions>;
154
  /** The workbox object for injectManifest */
155
  injectManifest?: Partial<CustomInjectManifestOptions>;
156
  /** Override Vite's base options only for PWA @default base options from Vite */
157
  base?: string;
158
  /** Public resources to be added to the PWA manifest */
159
  includeAssets?: string | string[];
160
  /** Include manifest icons in service worker precache @default true */
161
  includeManifestIcons?: boolean;
162
  /** Disable service worker registration and generation @default false */
163
  disable?: boolean;
164
  /** Vite PWA Integration */
165
  integration?: PWAIntegration;
166
  /** Development options */
167
  devOptions?: DevOptions;
168
  /** Unregister the service worker @default false */
169
  selfDestroying?: boolean;
170
  /** Configure build path for Laravel integrations @default vite.base */
171
  buildBase?: string;
172
  /** PWA assets generation and injection @experimental */
173
  pwaAssets?: PWAAssetsOptions;
174
  /** Show maximumFileSizeToCacheInBytes warning @default false */
175
  showMaximumFileSizeToCacheInBytesWarning?: boolean;
176
}
177

178
interface RegisterSWOptions {
179
  immediate?: boolean;
180
  onNeedRefresh?: () => void;
181
  onOfflineReady?: () => void;
182
  onRegistered?: (registration?: ServiceWorkerRegistration) => void;
183
  onRegisteredSW?: (swScriptUrl: string, registration?: ServiceWorkerRegistration) => void;
184
  onRegisterError?: (error: any) => void;
185
}
186

187
interface ManifestOptions {
188
  /** @default _npm_package_name_ */
189
  name?: string;
190
  /** @default _npm_package_name_ */
191
  short_name?: string;
192
  /** @default _npm_package_description_ */
193
  description?: string;
194
  /** @default [] */
195
  icons?: IconResource[];
196
  /** File handlers configuration @default [] */
197
  file_handlers?: {
198
    action: string;
199
    accept: Record<string, string[]>;
200
  }[];
201
  /** @default routerBase */
202
  start_url?: string;
203
  /** Restricts what web pages can be viewed while the manifest is applied */
204
  scope?: string;
205
  /** A string that represents the identity for the application */
206
  id?: string;
207
  /** @default 'standalone' */
208
  display?: Display;
209
  /** @default [] */
210
  display_override?: DisplayOverride[];
211
  /** Defines the default orientation for all the website's top-level */
212
  orientation?: 'any' | 'natural' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'portrait' | 'portrait-primary' | 'portrait-secondary';
213
  /** @default '#42b883' */
214
  theme_color?: string;
215
  /** @default '#ffffff' */
216
  background_color?: string;
217
  /** @default 'en' */
218
  lang?: string;
219
  /** @default 'ltr' */
220
  dir?: 'ltr' | 'rtl';
221
  categories?: string[];
222
  screenshots?: ScreenshotResource[];
223
  shortcuts?: ShortcutResource[];
224
  related_applications?: RelatedApplication[];
225
  prefer_related_applications?: boolean;
226
}
227

228
interface IconResource {
229
  src: string;
230
  sizes?: string;
231
  type?: string;
232
  purpose?: 'monochrome' | 'maskable' | 'any' | string | ('monochrome' | 'maskable' | 'any')[];
233
}
234

235
type Display = 'fullscreen' | 'standalone' | 'minimal-ui' | 'browser';
236
type DisplayOverride = Display | 'window-controls-overlay';
237
```
238

239
## Constants
240

241
```typescript { .api }
242
const cachePreset: RuntimeCaching[];
243
const defaultInjectManifestVitePlugins: string[];
244
```