Getting Started

TIP

If you use the default registerType which is prompt, and you want to prompt the users to reload, then you could use our framework modules.

But if you:

use autoUpdate
don't like autoUpdate, but also don't feel it's necessary to prompt
use injectManifest

Then, you don't need to learn the framework stuff.

This plugin is Framework-agnostic and so you can use it with Vanilla JavaScript, TypeScript and with any framework.

Type declarations

You can find all the vite-plugin-pwa virtual modules declarations in the following types.ts module.

TIP

If your TypeScript build step or IDE complain about not being able to find modules or type definitions on imports, add the following to the compilerOptions.types array of your tsconfig.json:

json

{
  "compilerOptions": {
    "types": [
      "vite-plugin-pwa/client"
    ]
  }
}

{
  "compilerOptions": {
    "types": [
      "vite-plugin-pwa/client"
    ]
  }
}

Or you can add the following reference in any of your d.ts files (for example, in vite-env.d.ts or global.d.ts):

/// <reference types="vite-plugin-pwa/client" />

/// <reference types="vite-plugin-pwa/client" />

declare module 'virtual:pwa-register' {
  export interface RegisterSWOptions {
    immediate?: boolean
    onNeedRefresh?: () => void
    onOfflineReady?: () => void
    /**
     * Called only if `onRegisteredSW` is not provided.
     *
     * @deprecated Use `onRegisteredSW` instead.
     * @param registration The service worker registration if available.
     */
    onRegistered?: (registration: ServiceWorkerRegistration | undefined) => void
    /**
     * Called once the service worker is registered (requires version `0.12.8+`).
     *
     * @param swScriptUrl The service worker script url.
     * @param registration The service worker registration if available.
     */
    onRegisteredSW?: (swScriptUrl: string, registration: ServiceWorkerRegistration | undefined) => void
    onRegisterError?: (error: any) => void
  }

  export function registerSW(options?: RegisterSWOptions): (reloadPage?: boolean) => Promise<void>
}

declare module 'virtual:pwa-register' {
  export interface RegisterSWOptions {
    immediate?: boolean
    onNeedRefresh?: () => void
    onOfflineReady?: () => void
    /**
     * Called only if `onRegisteredSW` is not provided.
     *
     * @deprecated Use `onRegisteredSW` instead.
     * @param registration The service worker registration if available.
     */
    onRegistered?: (registration: ServiceWorkerRegistration | undefined) => void
    /**
     * Called once the service worker is registered (requires version `0.12.8+`).
     *
     * @param swScriptUrl The service worker script url.
     * @param registration The service worker registration if available.
     */
    onRegisteredSW?: (swScriptUrl: string, registration: ServiceWorkerRegistration | undefined) => void
    onRegisterError?: (error: any) => void
  }

  export function registerSW(options?: RegisterSWOptions): (reloadPage?: boolean) => Promise<void>
}

Import Virtual Modules

vite-plugin-pwa plugin exposes a Vite virtual module to interact with the service worker.

TIP

You only need to import the virtual modules exposed by vite-plugin-pwa plugin when you need to interact with the user, otherwise you don't need to import any of them, that is, when using registerType: 'prompt' or when using registerType: 'autoUpdate' and you want to inform the user that the application is ready to work offline.

Auto Update

You must import the virtual module when you configure registerType: 'autoUpdate' and you want your application inform the user when the application is ready to work offline:

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

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

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

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

You 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.

Prompt For Update

When using registerType: 'prompt', you must import the virtual module:

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.

Custom Vite Virtual Modules

vite-plugin-pwa plugin also exposes a set of virtual modules for Vue 3, React, Svelte, SolidJS and Preact.

These custom virtual modules will expose a wrapper for virtual:pwa-register using framework reactivity system, that is:

virtual:pwa-register/vue: ref for Vue 3
virtual:pwa-register/react: useState for React
virtual:pwa-register/svelte: writable for Svelte
virtual:pwa-register/solid: createSignal for SolidJS
virtual:pwa-register/preact: useState for Preact

Note: for Vue 2 you need to use a custom mixin provided on Vue 2 section.

Frameworks

These custom virtual modules will expose a wrapper for virtual:pwa-register using framework reactivity system, that is:

Getting Started #

Type declarations #

Import Virtual Modules #

Auto Update #

Prompt For Update #

Custom Vite Virtual Modules #

Frameworks #