{"id":20678,"library":"vite-plugin-pwa","title":"vite-plugin-pwa","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/vite-pwa/vite-plugin-pwa","tags":["javascript","react","pwa","vue","vitepress","preact","svelte","sveltekit","workbox","typescript"],"install":[{"cmd":"npm install vite-plugin-pwa","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-pwa","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-pwa","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: requires Vite 3.1+, 4, 5, 6, or 7","package":"vite","optional":false},{"reason":"peer dependency: used for service worker bundling","package":"workbox-build","optional":false},{"reason":"peer dependency: provides the Workbox window module for client-side registration and update handling","package":"workbox-window","optional":false},{"reason":"optional peer: for generating PWA assets like icons and splash screens","package":"@vite-pwa/assets-generator","optional":true}],"imports":[{"note":"VitePWA is a named export, not a default export.","wrong":"import VitePWA from 'vite-plugin-pwa'","symbol":"VitePWA","correct":"import { VitePWA } from 'vite-plugin-pwa'"},{"note":"The registerSW helper is exported from the 'vite-plugin-pwa/register' subpath, not the main entry.","wrong":"import { registerSW } from 'vite-plugin-pwa'","symbol":"registerSW","correct":"import { registerSW } from 'vite-plugin-pwa/register'"},{"note":"For Vue 3, useRegisterSW is a virtual module; other frameworks have similar virtual modules (pwa-register/react, pwa-register/svelte, etc.).","wrong":"import { useRegisterSW } from 'vite-plugin-pwa'","symbol":"useRegisterSW","correct":"import { useRegisterSW } from 'virtual:pwa-register/vue'"}],"quickstart":{"code":"// vite.config.ts\nimport { VitePWA } from 'vite-plugin-pwa'\nexport default defineConfig({\n  plugins: [\n    VitePWA({\n      registerType: 'autoUpdate',\n      manifest: {\n        name: 'My App',\n        short_name: 'App',\n        description: 'My Awesome App',\n        theme_color: '#ffffff',\n        icons: [\n          {\n            src: 'icon-192x192.png',\n            sizes: '192x192',\n            type: 'image/png'\n          },\n          {\n            src: 'icon-512x512.png',\n            sizes: '512x512',\n            type: 'image/png'\n          }\n        ]\n      },\n      workbox: {\n        globPatterns: ['**/*.{js,css,html,ico,png,svg}']\n      }\n    })\n  ]\n})","lang":"typescript","description":"Configures vite-plugin-pwa with auto-update service worker, custom manifest, and Workbox caching for static assets."},"warnings":[{"fix":"Upgrade Vite to 3.1+ or pin vite-plugin-pwa to v0.12.x.","message":"VitePWA plugin now requires Vite 3.1 or above (since v0.13).","severity":"breaking","affected_versions":">=0.13"},{"fix":"Ensure Node.js version is 16 or higher.","message":"Workbox v7 dropped support for Node 14 (requires Node 16+).","severity":"breaking","affected_versions":">=0.16"},{"fix":"Upgrade to Vite 5+ or use vite-plugin-pwa v0.16.x.","message":"From v0.17, Vite 5 is the minimum required version.","severity":"breaking","affected_versions":">=0.17"},{"fix":"See migration guide: https://vite-pwa-org.netlify.app/guide/update.html","message":"The `registerType: 'prompt'` is deprecated in favor of manual update handling using workbox-window.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Set VitePWA({ devOptions: { enabled: true } }) to enable SW in dev mode.","message":"When using generateSW strategy, the service worker file may not be regenerated in development mode unless devOptions.enabled is set to true.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to v0.21.2 or explicitly set theme_color and description in the manifest.","message":"Manifest `theme_color` and `description` defaults may not apply if a manifest object is provided without those fields (fixed in v0.21.2).","severity":"gotcha","affected_versions":"<0.21.2"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Upgrade Vite to version 3.1 or higher.","cause":"Old version of Vite (<3.1) incompatible with vite-plugin-pwa v0.13+.","error":"Error: [vite-plugin-pwa] The VitePWA plugin requires Vite >=3.1.0"},{"fix":"Ensure workbox generates the service worker with correct Content-Type. In VitePWA config, set `workbox: { swSrc: 'src/sw.js', ... }` for injectManifest strategy.","cause":"Service worker script served with incorrect MIME type, often due to missing or incorrect workbox configuration.","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')."},{"fix":"Add `// self.__WB_MANIFEST` in your service worker source file to mark where workbox will inject the manifest.","cause":"Using injectManifest strategy without including the magic comment `self.__WB_MANIFEST` in the custom service worker file.","error":"Error: The custom injection point `self.__WB_MANIFEST` does not exist in your service worker source file."},{"fix":"No fix needed; it's informational. To suppress, use registerType: 'autoUpdate' instead.","cause":"This is a warning from update prompt logic (registerType: 'prompt'), not an error. It indicates a new SW version detected.","error":"WARN: The new app version is available. Please close or refresh the tab."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}