Skip to content
On this page

Prompt for new content refreshing

Prompt for update for new content dialog image with the update and cancel button

Plugin Configuration

Since this is the default behavior for the registerType plugin option, you don't need to configure it.

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 precache 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 precache manifest, but their revision will not change from the previous one.

Precache Manifest Entry Revision

The precache manifest entry revision is just a MD5 hash of the asset content, if an asset is not modified, the calculated hash will be always the same.

When the browser detects and installs the new version of your application, it will have in the cache storage 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 in the workbox entry of the plugin configuration.

When using the generateSW strategy, it is not necessary to configure 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 the following code in your plugin configuration:

ts
import { VitePWA } from 'vite-plugin-pwa'
export default defineConfig({
  plugins: [
    VitePWA({
      workbox: {
        cleanupOutdatedCaches: false
      }
    })
  ]
})
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:

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

Importing Virtual Modules

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

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

const updateSW = registerSW({
  onNeedRefresh() {},
  onOfflineReady() {},
})
import { registerSW } from 'virtual:pwa-register'

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

You will need to:

  • show a prompt to the user with refresh and cancel buttons inside onNeedRefresh method.
  • show a ready to work offline message to the user with an OK button inside onOfflineReady method.

When the user clicks the "refresh" button when onNeedRefresh called, then call updateSW() function; the page will reload and the up-to-date content will be served.

In any case, when the user clicks the Cancel or OK buttons in case onNeedRefresh or onOfflineReady respectively, close the corresponding showed prompt.

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:

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

registerSW({ /* ... */ })
import { registerSW } from 'virtual:pwa-register'

registerSW({ /* ... */ })

and then import it from your main.ts:

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

You can see the FAQ entry for more info.

Released under the MIT License.