Automatic reload

In order for the service worker to be registered, you must invoke the registerSW method from the virtual:pwa-register module.

With this option, once the service worker detects new content available, then it will update caches and will reload all browser windows/tabs with the application opened automatically to take the control.

The disadvantage of using this option is that the user can lose data in other browser windows / tabs in which the application is open and is filling in a form.

If your application has forms, we recommend you to change the behavior to use default prompt option to allow the user decide when to update the content of the application.

Setup

Go to Generate Service Worker section for basic configuration options.

With this option, the plugin will force workbox.clientsClaim and workbox.skipWaiting to true.

You must add registerType: 'autoUpdate' to Vite PWA options in your vite.config.ts file:

VitePWA({
  registerType: 'autoUpdate'
})

Cleanup Outdated Caches

The service worker will store all your application assets in a browser cache (or set of caches). Every time you make changes to your application and rebuild it, the service worker will be also rebuild, including in its cache manifest all new modified assets, which will have their revision changed (all assets that have been modified will have a new version). Assets that have not been modified will also be included in the service worker manifest cache, but their revision will not change from the previous version.

When the user installs the new version of the application, we will have on the service worker cache all new assets and also the old ones. To delete old assets (from previous versions that are no longer necessary), you have to configure an option on the workbox entry of the plugin configuration.

When using the generateSW strategy, it is not necessary to activate it, the plugin will activate it by default.

We strongly recommend you to NOT deactivate the option. If you are curious, you can deactivate it using this code on your plugin configuration:

import { VitePWA } from 'vite-plugin-pwa'
export default defineConfig({
  plugins: [
    VitePWA({
      workbox: {
        cleanupOutdatedCaches: false  
      }  
    })
  ]    
})

Generate SW Source Map

Since plugin version 0.11.2, your service worker's source map will not be generated as it uses the build.sourcemap option from the Vite config, which by default is false.

Your service worker source map will be generated when Vite's build.sourcemap configuration option has the value true, 'online' or 'hidden', and you have not configured the workbox.sourcemap option in the plugin configuration. If you configure the workbox.sourcemap option, the plugin will not change that value.

If you want to generate the source map of your service worker, you can use this code:

import { VitePWA } from 'vite-plugin-pwa'
export default defineConfig({
  plugins: [
    VitePWA({
      workbox: {
        sourcemap: true  
      }  
    })
  ]    
})

Runtime

You must include the following code on your main.ts or main.js file:

import { registerSW } from 'virtual:pwa-register'

const updateSW = registerSW({
  onOfflineReady() {},
})

You will need to show a ready to work offline message to the user with an OK button inside onOfflineReady method.

When the user clicks the OK button, just hide the prompt shown on onOfflineReady method.

SSR/SSG

If you are using SSR/SSG, you need to import virtual:pwa-register module using dynamic import and checking if window is not undefined.

You can register the service worker on src/pwa.ts module:

import { registerSW } from 'virtual:pwa-register'

registerSW({ ... })

and then import it from your main.ts:

if (typeof window !== 'undefined') {
  import('./pwa')
}

You can see the FAQ entry for more info.