vite-plugin-pwa

1.2.0 verified Sat Apr 25 auth: no javascript

Zero-config PWA plugin for Vite that integrates Workbox for service worker generation, Web App Manifest injection, and offline support. Current stable version is 1.2.0. Releases occur frequently, with support for Vite 3.1+ through 7. Key differentiators: framework-agnostic (Vue, React, Svelte, etc.), automatic service worker handling with generateSW or injectManifest strategies, built-in prompt for new content updates, and optional PWA asset generation.

Common errors

error Error: [vite-plugin-pwa] The VitePWA plugin requires Vite >=3.1.0 ↓

cause Old version of Vite (<3.1) incompatible with vite-plugin-pwa v0.13+.

fix

Upgrade Vite to version 3.1 or higher.

error Uncaught (in promise) TypeError: Failed to register a ServiceWorker for scope ('https://example.com/') with script ('https://example.com/sw.js'): The script has an unsupported MIME type ('text/plain'). ↓

cause Service worker script served with incorrect MIME type, often due to missing or incorrect workbox configuration.

fix

Ensure workbox generates the service worker with correct Content-Type. In VitePWA config, set workbox: { swSrc: 'src/sw.js', ... } for injectManifest strategy.

error Error: The custom injection point `self.__WB_MANIFEST` does not exist in your service worker source file. ↓

cause Using injectManifest strategy without including the magic comment `self.__WB_MANIFEST` in the custom service worker file.

fix

Add // self.__WB_MANIFEST in your service worker source file to mark where workbox will inject the manifest.

error WARN: The new app version is available. Please close or refresh the tab. ↓

cause This is a warning from update prompt logic (registerType: 'prompt'), not an error. It indicates a new SW version detected.

fix

No fix needed; it's informational. To suppress, use registerType: 'autoUpdate' instead.

Warnings

breaking VitePWA plugin now requires Vite 3.1 or above (since v0.13). ↓

fix Upgrade Vite to 3.1+ or pin vite-plugin-pwa to v0.12.x.

breaking Workbox v7 dropped support for Node 14 (requires Node 16+). ↓

fix Ensure Node.js version is 16 or higher.

breaking From v0.17, Vite 5 is the minimum required version. ↓

fix Upgrade to Vite 5+ or use vite-plugin-pwa v0.16.x.

deprecated The `registerType: 'prompt'` is deprecated in favor of manual update handling using workbox-window. ↓

fix See migration guide: https://vite-pwa-org.netlify.app/guide/update.html

gotcha When using generateSW strategy, the service worker file may not be regenerated in development mode unless devOptions.enabled is set to true. ↓

fix Set VitePWA({ devOptions: { enabled: true } }) to enable SW in dev mode.

gotcha Manifest `theme_color` and `description` defaults may not apply if a manifest object is provided without those fields (fixed in v0.21.2). ↓

fix Upgrade to v0.21.2 or explicitly set theme_color and description in the manifest.

Install

npm install vite-plugin-pwa

yarn add vite-plugin-pwa

pnpm add vite-plugin-pwa

Imports

VitePWA

wrong

import VitePWA from 'vite-plugin-pwa'

correct

import { VitePWA } from 'vite-plugin-pwa'

VitePWA is a named export, not a default export.

registerSW
wrong
```
import { registerSW } from 'vite-plugin-pwa'
```
correct
```
import { registerSW } from 'vite-plugin-pwa/register'
```
The registerSW helper is exported from the 'vite-plugin-pwa/register' subpath, not the main entry.
useRegisterSW
wrong
```
import { useRegisterSW } from 'vite-plugin-pwa'
```
correct
```
import { useRegisterSW } from 'virtual:pwa-register/vue'
```
For Vue 3, useRegisterSW is a virtual module; other frameworks have similar virtual modules (pwa-register/react, pwa-register/svelte, etc.).

Quickstart

Configures vite-plugin-pwa with auto-update service worker, custom manifest, and Workbox caching for static assets.

// vite.config.ts
import { VitePWA } from 'vite-plugin-pwa'
export default defineConfig({
  plugins: [
    VitePWA({
      registerType: 'autoUpdate',
      manifest: {
        name: 'My App',
        short_name: 'App',
        description: 'My Awesome App',
        theme_color: '#ffffff',
        icons: [
          {
            src: 'icon-192x192.png',
            sizes: '192x192',
            type: 'image/png'
          },
          {
            src: 'icon-512x512.png',
            sizes: '512x512',
            type: 'image/png'
          }
        ]
      },
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg}']
      }
    })
  ]
})