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:

1. use autoUpdate
2. don't like autoUpdate, but also don't feel it's necessary to prompt
3. 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:

{
  "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" />

From version 0.14.5 you can also use types definition for each framework, instead of using vite-plugin-pwa/client, include only one of the following types:

{
  "compilerOptions": {
    "types": [
      "vite-plugin-pwa/react",
      "vite-plugin-pwa/preact",
      "vite-plugin-pwa/solid",
      "vite-plugin-pwa/svelte",
      "vite-plugin-pwa/vanillajs",
      "vite-plugin-pwa/vue"
    ]
  }
}

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

/// <reference types="vite-plugin-pwa/react" />
/// <reference types="vite-plugin-pwa/preact" />
/// <reference types="vite-plugin-pwa/solid" />
/// <reference types="vite-plugin-pwa/svelte" />
/// <reference types="vite-plugin-pwa/vanillajs" />
/// <reference types="vite-plugin-pwa/vue" />

declare module 'virtual:pwa-register' {
  import type { RegisterSWOptions } from 'vite-plugin-pwa/types'

  export type { RegisterSWOptions }

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

where vite-plugin-pwa/types is:

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
}

Accessing PWA Info

From version 0.12.8, vite-plugin-pwa exposes a new Vite virtual module to access the PWA info: virtual:pwa-info.

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:

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

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/info" />

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() {}
})

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() {}
})

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:

• Vue
• React
• Svelte
• SvelteKit
• SolidJS
• Preact
• VitePress
• îles
• Astro
• Nuxt 3