vite-plugin-pwa: adding a service worker and web app manifest to a Vite build

The gap vite-plugin-pwa fills between a Vite build and an installable app

A Vite production build emits HTML, JavaScript and CSS. It does not emit a web app manifest, and it does not emit a service worker, so the browser has nothing to install and nothing to serve from cache when the network drops. vite-plugin-pwa is a Vite plugin that closes that gap at build time: it injects the manifest into the generated HTML and produces a service worker through Workbox. The README describes it as a "Zero-config PWA Framework-agnostic Plugin for Vite", and the package keywords list react, vue, preact, svelte, solidjs and vitepress, which matches the client type declaration files shipped at the repository root (react.d.ts, vue.d.ts, svelte.d.ts, solid.d.ts, preact.d.ts, vanillajs.d.ts).

The audience is narrower than "anyone building a PWA". It is developers who have already chosen Vite as their bundler and want offline behaviour without maintaining a service worker by hand. If your build does not go through Vite, nothing here applies.

How the plugin turns a Vite build into a service worker and manifest

The mechanism is a build-time plugin. You add VitePWA() to the plugins array, and the plugin hooks into the Vite build pipeline. According to the README, offline support comes from a generated service worker built on Workbox, and the manifest is auto injected. The README also lists stale-while-revalidate as a built-in strategy and describes "automatic reload when new content is available", so the default behaviour is not a pure cache-first scheme.

The repository layout shows where the pieces live. src/ holds the plugin source, types/ holds published type declarations, and the root .d.ts files are the per-framework client type entry points exposed through the package exports map. The README points readers to client.d.ts for built-in framework support and to src/types.ts for the full configuration surface, which is the honest answer to "what can I configure": the README itself does not enumerate options.

One design consequence is worth stating plainly. Because the service worker is generated during the build, the caching strategy is fixed at build time. Changing how a route is cached means changing configuration and rebuilding, not editing a running worker.

Installing vite-plugin-pwa and getting a first build with a generated worker

The README gives the install command for npm, yarn and pnpm, and marks the package as a dev dependency. It also states version requirements: from v0.17 the plugin requires Vite 5, and from v0.16 it requires Node 16 or above, because Workbox v7 requires Node 16 or above.

npm i vite-plugin-pwa -D

After installation, register the plugin in your Vite config. The README shows exactly this shape, with VitePWA() called with no arguments to get the built-in defaults.

// vite.config.js / vite.config.ts
import { VitePWA } from 'vite-plugin-pwa'

export default {
  plugins: [
    VitePWA()
  ]
}

Run your normal Vite build and inspect the output directory. What you should see is a generated service worker alongside the usual assets, plus a manifest link injected into the built HTML. The README does not print the default filenames, so read them from your own dist output rather than assuming. For a fuller configuration walkthrough the README sends you to the guide at vite-pwa-org.netlify.app.

The repository ships eleven example projects under examples/, including vanilla-js-custom-sw, vanilla-ts-dev-options, vue-basic-cdn, react-router, svelte-routify, sveltekit-pwa and assets-generator. Those directories are the fastest way to see a working configuration for your framework, since the README's own usage snippet stops at the empty call.

Where vite-plugin-pwa stops: push, server state and framework overlap

The README lists no push notification support. Searching the feature list for push returns nothing, and the topics and keywords cover offline support, manifest injection, static asset handling and development debugging, not messaging. If push is a requirement, this plugin does not address it, and you would be adding a separate notification layer on top of the generated worker.

The second boundary is the framework. The README claims integration with SvelteKit, Nuxt 3, VitePress, Astro, iles and Remix. That claim sits alongside the fact that some of those frameworks already generate or manage a service worker themselves, which means the plugin's role there is narrower than in a plain Vite app. The README does not explain how the two layers divide responsibility, so treat the integration list as a starting point for reading the docs, not as a guarantee that the plugin is doing the caching.

Third, the build-time model has a cost. Every change to caching behaviour is a config change plus a rebuild. Teams that need to adjust caching from a server, or that want per-user cache policy, are outside what this plugin was built for.

vite-plugin-pwa compared with hand-written Workbox or a framework PWA layer

The most direct alternative is using Workbox directly with workbox-build or workbox-webpack-plugin style tooling: you write the service worker and the precache manifest yourself, and you wire it into the build. The difference is where the knowledge lives. With vite-plugin-pwa, the plugin owns the generation step and the defaults, and you configure through the plugin's options; with raw Workbox, you own the strategy code and the injection step. Raw Workbox gives you control the plugin does not expose without configuration, and it costs you the Vite-specific wiring that the plugin already does. If your caching rules are unusual, or you need to share worker code across more than one bundler, the raw route is the one that does not fight the plugin's defaults.

The other alternative is not a library at all: relying on whatever PWA support your meta framework ships. The README positions vite-plugin-pwa as integrating with SvelteKit, Nuxt 3, VitePress, Astro, iles and Remix, but when a framework already produces a service worker, adding this plugin means two systems with overlapping jobs. The difference in approach is that the framework layer is usually tied to the framework's routing and asset conventions, while vite-plugin-pwa is framework-agnostic and driven by Vite's build output.

Release cadence, licence and the cost of upgrading

The last push to the repository was on 2026-05-05, and the most recent release, v1.3.0, is dated the same day. Before that, v1.2.0 landed on 2025-11-27 and v1.1.0 on 2025-10-13. The spacing suggests a project that releases when there is something to release rather than on a schedule, and the repository is not archived.

The upgrade cost is concentrated in the version gates the README documents: Vite 5 from v0.17, Node 16 or above from v0.16. Those are the constraints that decide whether a project can move to the current line at all. The package declares engines.node as ">=16.0.0", which matches the README, and it is published as both ESM and CommonJS through the exports map, so the module format of your project is not a blocker.

The licence is MIT, stated in both the README and package.json. MIT is permissive, which in practice means you can ship the generated service worker inside a commercial product; the repository does not add a separate service worker licence, and the README offers no further guidance. That is a description of the licence text, not advice about your situation.

Editorial conclusion

Adopt vite-plugin-pwa if you already build with Vite 5 and want a Workbox service worker plus an injected manifest without writing caching rules by hand; the README points to client.d.ts and src/types.ts when you outgrow the defaults. Skip it if your framework already generates a service worker, or if you need push notifications, which the README never mentions. Before committing, check that your Node version is 16 or above, confirm VitePWA() is placed in the plugins array of vite.config.ts, and inspect the generated service worker in the build output to see which assets were precached.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vite-pwa/vite-plugin-pwa on GitHub