New content available, click on reload button to update.
```
## PWA Assets
This new feature includes:
* new `NuxtPwaAssets` component to include the PWA assets in your HTML pages: if you're using `VitePwaManifest` or `NuxtPwaManifest` component, replace it with `NuxtPwaAssets`: it will inject the web manifest link, the `theme-color` meta and the PWA icon links.
* new `PwaAppleImage`, `PwaAppleSplashScreenImage`, `PwaFaviconImage`, `PwaMaskableImage` and `PwaTransparentImage` components to use PWA icons in your code base
* new `useApplePwaIcon`, `useAppleSplashScreenPwaIcon`, `useFaviconPwaIcon`, `useMaskablePwaIcon` and `useTransparentPwaIcon` composables
* injects `$pwaIcons` with all configured PWA icons: you can use them via `useNuxtApp().$pwaIcons` or inside your Vue templates
New components, composables and `$pwaIcons` injection are statically analisable, that's, pwa icons types are generated when running `nuxt prepare` command: if you want to disable the PWA assets you don't need to remove the code (you can remove unused components/code later if you want to remove the new feature).
---
---
url: /guide/periodic-sw-updates.md
---
# Periodic Service Worker Updates
:::info
If you're not importing any of the virtual modules provided by `vite-plugin-pwa` you'll need to figure out how to configure it, it is out of the scope of this guide.
:::
As explained in [Manual Updates](https://web.dev/articles/service-worker-lifecycle#manual_updates) entry in [The Service Worker Lifecycle](https://web.dev/articles/service-worker-lifecycle) article, you can use this code to configure periodic service worker updates on your application on your `main.ts` or `main.js`:
::: details main.ts / main.js
```ts
import { registerSW } from 'virtual:pwa-register'
const intervalMS = 60 * 60 * 1000
const updateSW = registerSW({
onRegistered(r) {
r && setInterval(() => {
r.update()
}, intervalMS)
}
})
```
:::
The interval must be in milliseconds, in the example above it is configured to check the service worker every hour.
## Handling Edge Cases
::: info
From version `0.12.8+` we have a new option, `onRegisteredSW`, and `onRegistered` has been deprecated. If `onRegisteredSW` is present, `onRegistered` will never be called.
:::
Previous script will allow you to check if there is a new version of your application available, but you will need also to deal with some edge cases like:
* server is down when calling the update method
* the user can go offline at any time
To mitigate previous problems, use this more complex snippet:
::: details main.ts / main.js
```ts
import { registerSW } from 'virtual:pwa-register'
const intervalMS = 60 * 60 * 1000
const updateSW = registerSW({
onRegisteredSW(swUrl, r) {
r && setInterval(async () => {
if (r.installing || !navigator)
return
if (('connection' in navigator) && !navigator.onLine)
return
const resp = await fetch(swUrl, {
cache: 'no-store',
headers: {
'cache': 'no-store',
'cache-control': 'no-cache',
},
})
if (resp?.status === 200)
await r.update()
}, intervalMS)
}
})
```
:::
---
---
url: /examples/preact.md
---
# Preact
The `Preact` example project can be found on [examples/preact-router](https://github.com/vite-pwa/vite-plugin-pwa/tree/main/examples/preact-router) package/directory.
The router used on this example project is [preact-router](https://github.com/preactjs/preact-router).
To test `new content available`, you should rerun the corresponding script, and then refresh the page.
If you are running an example with `Periodic SW updates`, you will need to wait 1 minute:
## Executing the examples
## generateSW
## injectManifest
---
---
url: /frameworks/preact.md
---
# Preact
You can use the built-in `Vite` virtual module `virtual:pwa-register/preact` for `Preact` which will return `useState` stateful values (`useState
{ (offlineReady || needRefresh)
&&
}
)
}
export default ReloadPrompt
```
:::
and its corresponding `ReloadPrompt.css` styles file:
::: details ReloadPrompt.css
```css
.ReloadPrompt-container {
padding: 0;
margin: 0;
width: 0;
height: 0;
}
.ReloadPrompt-toast {
position: fixed;
right: 0;
bottom: 0;
margin: 16px;
padding: 12px;
border: 1px solid #8885;
border-radius: 4px;
z-index: 1;
text-align: left;
box-shadow: 3px 4px 5px 0 #8885;
background-color: white;
}
.ReloadPrompt-toast-message {
margin-bottom: 8px;
}
.ReloadPrompt-toast-button {
border: 1px solid #8885;
outline: none;
margin-right: 5px;
border-radius: 2px;
padding: 3px 10px;
}
```
:::
## Periodic SW Updates
As explained in [Periodic Service Worker Updates](/guide/periodic-sw-updates), you can use this code to configure this behavior on your application with the virtual module `virtual:pwa-register/preact`:
```ts
import { useRegisterSW } from 'virtual:pwa-register/preact'
const intervalMS = 60 * 60 * 1000
const updateServiceWorker = useRegisterSW({
onRegistered(r) {
r && setInterval(() => {
r.update()
}, intervalMS)
}
})
```
The interval must be in milliseconds, in the example above it is configured to check the service worker every hour.
---
---
url: /guide/prompt-for-update.md
---
# Prompt for new content refreshing
## Plugin Configuration
Since this is the default behavior for the `registerType` plugin option, you don't need to configure it.
### Cleanup Outdated Caches
### Inject Manifest Source Map
### Generate SW Source Map
## 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() {},
})
```
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
---
---
url: /guide/pwa-minimal-requirements.md
---
# PWA Minimal Requirements
Previous steps in this guide, are the minimal requirements and configuration to create the [Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) and the service worker when you build your application, but you'll need to include more options to meet PWA Minimal Requirements.
Your application **must** meet the PWA Minimal Requirements before deploying it to production or when testing your build on local: for example, when testing your PWA application on local using `LightHouse`.
To make your PWA application installable (one of the requirements), you will need to modify your application entry point, add some minimal entries to your `Web App Manifest`, allow search engines to crawl all your application pages and configure your server properly (only for production, on local you can use `https-localhost` dependency and `node`).
Check also the new [PWA Minimal Requirements](/assets-generator/#pwa-minimal-icons-requirements) page in the [PWA Assets Generator](/assets-generator/) section.
## Entry Point
Your application entry point (usually `index.html`) **must** have the following entries in the `` section:
* mobile viewport configuration
* a title
* a description
* a favicon, check the following pages: https://dev.to/masakudamatsu/favicon-nightmare-how-to-maintain-sanity-3al7 and this old one https://www.leereamsnyder.com/blog/favicons-in-2021
* a link for `apple-touch-icon`
* a link for `mask-icon` (right now there is no need to provide a `mask-icon`)
* a meta entry for `theme-color`
For example, a minimal configuration (you must provide all the icons and images):
```html
{ offlineReady
? App ready to work offline
: New content available, click on reload button to update.
}
{ needRefresh && }
{ (offlineReady || needRefresh)
&&
}
)
}
export default ReloadPrompt
```
:::
and its corresponding `ReloadPrompt.css` styles file:
:::details ReloadPrompt.css
```css
.ReloadPrompt-container {
padding: 0;
margin: 0;
width: 0;
height: 0;
}
.ReloadPrompt-toast {
position: fixed;
right: 0;
bottom: 0;
margin: 16px;
padding: 12px;
border: 1px solid #8885;
border-radius: 4px;
z-index: 1;
text-align: left;
box-shadow: 3px 4px 5px 0 #8885;
background-color: white;
}
.ReloadPrompt-toast-message {
margin-bottom: 8px;
}
.ReloadPrompt-toast-button {
border: 1px solid #8885;
outline: none;
margin-right: 5px;
border-radius: 2px;
padding: 3px 10px;
}
```
:::
## Periodic SW Updates
As explained in [Periodic Service Worker Updates](/guide/periodic-sw-updates), you can use this code to configure this behavior on your application with the virtual module `virtual:pwa-register/react`:
```ts
import { useRegisterSW } from 'virtual:pwa-register/react'
const intervalMS = 60 * 60 * 1000
const updateServiceWorker = useRegisterSW({
onRegistered(r) {
r && setInterval(() => {
r.update()
}, intervalMS)
}
})
```
The interval must be in milliseconds, in the example above it is configured to check the service worker every hour.
---
---
url: /guide/register-service-worker.md
---
# Register Service Worker
`vite-plugin-pwa` plugin will register the service worker automatically for you, using the `injectRegister` configuration option (**optional**).
If you want to configure the `injectRegister` plugin option:
```ts
import { VitePWA } from 'vite-plugin-pwa'
export default defineConfig({
plugins: [
VitePWA({
injectRegister: 'auto'
})
]
})
```
The `injectRegister` plugin configuration option, will control how to register the service worker in your application:
* `inline`: injects a simple register script, inlined in the application entry point
* `script`: injects a `script` tag in the `head` with the `src` attribute to a generated script to register the service worker
* `script-defer` : injects a `script` tag with `defer` attribute in the `head` with the `src` attribute to a generated script to register the service worker
* `null` (manual): do nothing, you will need to register the service worker yourself, or import any of the virtual modules exposed by the plugin
* **`auto` (default value)**: depends on whether you use any of the virtual modules exposed by the plugin, it will do nothing or switch to `script` mode
You can find more information about the virtual modules exposed by the plugin in the [Frameworks](/frameworks/) section.
## Inline Registration
When configuring `injectRegister: 'inline'` in the plugin configuration, the plugin will inline a head script adding in to your application entry point:
::: details **inlined head script**
```html
```
:::
## Script Registration
When configuring `injectRegister: 'script' | 'script-defer'` in the plugin configuration, the plugin will generate a `registerSW.js` script adding it to your application entry point:
::: details **head script**
```html
```
:::
::: details **/registerSW.js**
```js
if ('serviceWorker' in navigator) {
window.addEventListener('load', () => {
navigator.serviceWorker.register('/sw.js', { scope: '/' })
})
}
```
:::
## Manual Registration
When configuring `injectRegister: null` in the plugin configuration, the plugin will do nothing, you must register the service workbox manually yourself.
Or you can import any of the virtual modules exposed by the plugin.
If you're using `injectManifest` strategy in development with `devOptions` enabled, you should check [injectManifest development section](/guide/development#injectmanifest-strategy) to get details on getting the right ServiceWorker URL for your development setup.
## Auto Registration
If your application code base is not importing any of the virtual modules exposed by the plugin, the plugin will fallback to [Script Registration](/guide/register-service-worker#script-registration), otherwise, the imported virtual module will register the service worker for you.
---
---
url: /examples/remix.md
---
# Remix
You can find a set of examples in the [@vite-pwa/remix integration repo](https://github.com/vite-pwa/remix/tree/main/examples).
---
---
url: /frameworks/remix.md
---
# Remix
::: warning
This PWA module can only be used with Vite.
:::
## Remix PWA module
`vite-plugin-pwa` provides the new `@vite-pwa/remix` module that will allow you to use `vite-plugin-pwa` in your Remix applications via `Vite` plugin and `Remix` preset.
You will need to install `@vite-pwa/remix`:
::: code-group
```bash [pnpm]
pnpm add -D @vite-pwa/remix
```
```bash [yarn]
yarn add -D @vite-pwa/remix
```
```bash [npm]
npm install -D @vite-pwa/remix
```
:::
Then in your Vite configuration file, import the `@vite-pwa/remix` helper and create the Remix PWA Preset and the Vite PWA Plugin and configure them:
```ts
// vite.config.js
import { vitePlugin as remix } from '@remix-run/dev'
import { installGlobals } from '@remix-run/node'
import { defineConfig } from 'vite'
import { RemixVitePWA } from '@vite-pwa/remix'
installGlobals()
const { RemixVitePWAPlugin, RemixPWAPreset } = RemixVitePWA()
export default defineConfig({
plugins: [
remix({
presets: [RemixPWAPreset()],
}),
RemixVitePWAPlugin({
// PWA options
})
]
})
```
Check Remix [PWA Options](https://github.com/vite-pwa/remix/blob/main/src/types.ts) for further details.
## Custom Service Worker
When using `injectManifest` strategy, `@vite-pwa/remix` exposes a virtual module `virtual:vite-pwa/remix/sw` with the Remix information you can consume in your service worker (configuration from Remix and the `remix` PWA option):
```ts
import {
cleanupOutdatedCaches,
clientsClaimMode,
dynamicRoutes,
enablePrecaching,
navigateFallback,
promptForUpdate,
routes,
staticRoutes,
ssr,
} from 'virtual:vite-pwa/remix/sw'
```
If you are using TypeScript you can include `@vite-pwa/remix/remix-sw` in your `tsconfig.json`:
```json
{
"compilerOptions": {
"types": ["@vite-pwa/remix/remix-sw"]
}
}
```
or just include a triple slash comment in your service worker file:
```ts
///
{ offlineReady
? App ready to work offline
: New content available, click on reload button to update.
}
{ needRefresh && }
`
```
## globPatterns
If you need to include other assets that are not under Vite's `publicDir` option directory, you can use the `globPatterns` parameter of [workbox](https://developer.chrome.com/docs/workbox/modules/workbox-build#generatesw) or [injectManifest](https://developer.chrome.com/docs/workbox/modules/workbox-build#injectmanifest) plugin options.
::: warning
If you configure `globPatterns` on `workbox` or `injectManifest` plugin option, you **MUST** include all your assets patterns: `globPatterns` will be used by `workbox-build` to match files on `dist` folder.
By default, `globPatterns` will be `**/*.{js,css,html}`: `workbox` will use [glob primer](https://github.com/isaacs/node-glob#glob-primer) to match files using `globPatterns` as filter.
A common pitfall is to only include some assets and forget to add `css`, `js` and `html` assets pattern, and then your service worker will complain about missing resources.
For example, if you don't include `html` assets pattern, you will get this error from your service worker: **WorkboxError non-precached-url index.html**.
:::
To configure `globPatterns` you need to use `workbox` or `injectManifest` plugin option for`generateSW` and `injectManifest` strategies respectively:
::: code-group
```ts [generateSW]
VitePWA({
workbox: {
globPatterns: ['**/*.{js,css,html}'],
}
})
```
```ts [injectManifest]
VitePWA({
injectManifest: {
globPatterns: ['**/*.{js,css,html}'],
}
})
```
:::
---
---
url: /examples/svelte.md
---
# Svelte
The `Svelte` example project can be found on [examples/svelte-routify](https://github.com/vite-pwa/vite-plugin-pwa/tree/main/examples/svelte-routify) package/directory.
The router used on this example project is [@roxi/routify](https://routify.dev/).
To test `new content available`, you should rerun the corresponding script, and then refresh the page.
If you are running an example with `Periodic SW updates`, you will need to wait 1 minute:
## Executing the examples
## generateSW
## injectManifest
---
---
url: /frameworks/svelte.md
---
# Svelte
You can use the built-in `Vite` virtual module `virtual:pwa-register/svelte` for `Svelte` which will return `writable` stores (`Writable
{#if $needRefresh}
{/if}
{/if}
```
:::
## Periodic SW Updates
As explained in [Periodic Service Worker Updates](/guide/periodic-sw-updates), you can use this code to configure this behavior on your application with the virtual module `virtual:pwa-register/svelte`:
```ts
import { useRegisterSW } from 'virtual:pwa-register/svelte'
const intervalMS = 60 * 60 * 1000
const updateServiceWorker = useRegisterSW({
onRegistered(r) {
r && setInterval(() => {
r.update()
}, intervalMS)
}
})
```
The interval must be in milliseconds, in the example above it is configured to check the service worker every hour.
---
---
url: /examples/sveltekit.md
---
# SvelteKit
You can find a set of examples in the [@vite-pwa/sveltekit integration repo](https://github.com/vite-pwa/sveltekit/tree/main/examples).
---
---
url: /frameworks/sveltekit.md
---
# SvelteKit
::: tip
From version `^0.6.7`, `SvelteKitPWA` adds support for [Single-page apps](https://svelte.dev/docs/kit/single-page-apps): check [SPA](#spa) section for more information.
:::
::: tip
From version `^0.1.0`, `SvelteKitPWA` has SvelteKit `^1.0.0` as peer dependency.
:::
::: info
For `Type declarations`, `Prompt for update` and `Periodic SW Updates` go to [Svelte](/frameworks/svelte) entry.
:::
::: tip
If you're using `0.1.*` version of `SvelteKitPWA`, you should remove all references to [SvelteKit service worker module](https://kit.svelte.dev/docs/service-workers) to disable it on your application.
:::
## Installing @vite-pwa/sveltekit
To install the `@vite-pwa/sveltekit` plugin, just add it to your project as a `dev dependency`:
::: code-group
```bash [pnpm]
pnpm add -D @vite-pwa/sveltekit
```
```bash [yarn]
yarn add -D @vite-pwa/sveltekit
```
```bash [npm]
npm install -D @vite-pwa/sveltekit
```
:::
## Workbox Configuration
### globPatterns
`@vite-pwa/sveltekit` configures the following `globPatterns` for you (`workbox` or `injectManifest` option depending on the strategy configured):
* `workbox: { globPatterns: ['client/**/*.{js,css,ico,png,svg,webp,webmanifest}', 'prerendered/**/*.{html,json}'] }` or
* `injectManifest: { globPatterns: ['client/**/*.{js,css,ico,png,svg,webp,webmanifest}', 'prerendered/**/*.{html,json}'] }`
`@vite-pwa/sveltekit` configures the `.svelte-kit/output` directory as the `globDirectory` for the `workbox-build` process (`workbox` or `injectManifest` option depending on the strategy configured). This directory will contain all the files generated by SvelteKit when building your application as an intermediate step before the final adapter build. This directory will have the following structure:
* `client` directory: will contain all the client side files generated by SvelteKit (`.js`, `.css`) and all assets files in the static directory (`.ico`, `.png`, `.svg`, `.webp`).
* `prerendered/pages` directory: will contain all the prerendered pages (`.html`).
* `prerendered/dependencies/
{#if $needRefresh}
{/if}
{/if}
```
:::
## SvelteKit and Adapters
If you set certain SvelteKit options, you should also configure the PWA plugin properly using the `kit` option:
* [outDir](https://kit.svelte.dev/docs/configuration#outdir)
* [adapterFallback](https://github.com/sveltejs/kit/tree/master/packages/adapter-static#fallback)
* [trailingSlash](https://kit.svelte.dev/docs/configuration#trailingslash)
::: warning
Some kit options may have been moved/deprecated, review the SvelteKit documentation site:
* [trailingSlash](https://kit.svelte.dev/docs/page-options#trailingslash): now it should be configured in the page options, and so, we cannot control it in the plugin.
:::
### SPA
If you are using SvelteKit SPA mode, the `static-adapter` will create the fallback after `@vite-pwa/sveltekit` plugin generates the service worker, and so the plugin doesn't have access to the adapter fallback page to include the revision in the service worker precache manifest.
To generate the revision for the fallback page, the plugin will use the `.svelte-kit/output/client/_app/version.json` file.
You can configure the `spa.fallbackRevision` function to generate a custom revision.
## PWA Assets
We suggest you using external configuration file, `@vite-pwa/sveltekit` plugin will watch it for changes, avoiding dev server restarts. If you use inlined configuration, Vite will restart the dev server when changing any option.
To inject the PWA icons links and the `theme-color`, you can use the `virtual:pwa-assets/head` virtual module in your `+layout.svelte` component:
* add `import 'vite-plugin-pwa/pwa-assets';` to your `src/app.d.ts` file
* remove all links with rel `icon`, `apple-touch-icon` and `apple-touch-startup-image` from `
App ready to work offline
{{ offlineReady ? 'App ready to work offline' : 'New content available, click the reload button to update.' }}