Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VitePWA
✓ import { VitePWA } from 'vite-plugin-pwa'
✗ import VitePWA from 'vite-plugin-pwa'
VitePWA is a named export, not a default export.
registerSW
✓ import { registerSW } from 'vite-plugin-pwa/register'
✗ import { registerSW } from 'vite-plugin-pwa'
The registerSW helper is exported from the 'vite-plugin-pwa/register' subpath, not the main entry.
useRegisterSW
✓ import { useRegisterSW } from 'virtual:pwa-register/vue'
✗ import { useRegisterSW } from 'vite-plugin-pwa'
For Vue 3, useRegisterSW is a virtual module; other frameworks have similar virtual modules (pwa-register/react, pwa-register/svelte, etc.).
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}']
}
})
]
})
Errors
Common errors & fixes
Error: [vite-plugin-pwa] The VitePWA plugin requires Vite >=3.1.0
Old version of Vite (<3.1) incompatible with vite-plugin-pwa v0.13+.
fixUpgrade Vite to version 3.1 or higher.
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').
Service worker script served with incorrect MIME type, often due to missing or incorrect workbox configuration.
fixEnsure workbox generates the service worker with correct Content-Type. In VitePWA config, set `workbox: { swSrc: 'src/sw.js', ... }` for injectManifest strategy. Error: The custom injection point `self.__WB_MANIFEST` does not exist in your service worker source file.
Using injectManifest strategy without including the magic comment `self.__WB_MANIFEST` in the custom service worker file.
fixAdd `// self.__WB_MANIFEST` in your service worker source file to mark where workbox will inject the manifest.
WARN: The new app version is available. Please close or refresh the tab.
This is a warning from update prompt logic (registerType: 'prompt'), not an error. It indicates a new SW version detected.
fixNo fix needed; it's informational. To suppress, use registerType: 'autoUpdate' instead.
Audit
Dependencies
viterequiredpeer dependency: requires Vite 3.1+, 4, 5, 6, or 7
workbox-buildrequiredpeer dependency: used for service worker bundling
workbox-windowrequiredpeer dependency: provides the Workbox window module for client-side registration and update handling
@vite-pwa/assets-generatoroptionaloptional peer: for generating PWA assets like icons and splash screens