| 1 | --- |
| 2 | relates: |
| 3 | - vite-plugin-pwa: https://vite-pwa-org.netlify.app/ |
| 4 | - Workbox: https://developer.chrome.com/docs/workbox |
| 5 | tags: [build] |
| 6 | since: v52.17.0 |
| 7 | description: | |
| 8 | Opt-in PWA support that precaches all deck assets so a built deck runs fully offline. |
| 9 | --- |
| 10 | |
| 11 | # PWA / Offline Support |
| 12 | |
| 13 | Slides are often presented on an unfamiliar or locked-down machine, over a flaky or absent network. With the opt-in `pwa` option, `slidev build` generates a [service worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) (powered by [`vite-plugin-pwa`](https://vite-pwa-org.netlify.app/) and [Workbox](https://developer.chrome.com/docs/workbox)) that **precaches every deck asset** — JavaScript, CSS, and HTML plus all images, video, and audio — so once the served deck has loaded a first time, it runs entirely from the cache with no per-slide asset fetching mid-talk. |
| 14 | |
| 15 | ## Usage |
| 16 | |
| 17 | Enable it in the [headmatter](/custom/#headmatter) of your first slide: |
| 18 | |
| 19 | ```yaml |
| 20 | --- |
| 21 | pwa: true |
| 22 | --- |
| 23 | ``` |
| 24 | |
| 25 | The `pwa` option can be a boolean or a string to control when the service worker is active: |
| 26 | |
| 27 | - `false` (default) — no service worker. |
| 28 | - `true` — enabled in both dev and build. |
| 29 | - `'build'` — enabled in the built output only. |
| 30 | - `'dev'` — enabled in the dev server only. |
| 31 | |
| 32 | Since precaching every asset is heavy, `pwa` is **off by default** and should be enabled deliberately — most useful together with [`slidev build`](/guide/hosting) for a self-hosted deck you want to work offline. |
| 33 | |
| 34 | ## Installing the PWA Plugin |
| 35 | |
| 36 | PWA support is powered by [`vite-plugin-pwa`](https://vite-pwa-org.netlify.app/), which ships as an **optional peer dependency**. It is not installed by default, so decks that don't opt into `pwa` never download it. |
| 37 | |
| 38 | The first time you enable `pwa`, the Slidev CLI detects that the package is missing and prompts you to install it: |
| 39 | |
| 40 | ``` |
| 41 | ? The "pwa" option requires the "vite-plugin-pwa" package, which is not installed |
| 42 | in your project. Install it now? › (Y/n) |
| 43 | ``` |
| 44 | |
| 45 | Confirm the prompt and Slidev installs it for you with your project's package manager (or globally, when Slidev itself is installed globally). In a non-interactive environment (such as CI) the prompt can't be shown, so install it ahead of time instead: |
| 46 | |
| 47 | ```bash |
| 48 | npm i -D vite-plugin-pwa |
| 49 | ``` |
| 50 | |
| 51 | ## How It Works |
| 52 | |
| 53 | When you serve the built deck, the service worker downloads and caches all deck assets in the background. A small indicator in the bottom-right corner shows `Caching for offline…` while precaching is in progress, then briefly shows `Ready offline` once it completes. After that, disconnecting the network and reloading serves the whole deck — HTML, images, and video — from the cache. |
| 54 | |
| 55 | The plugin is a complete no-op when `pwa` is disabled, and the client registration and indicator are tree-shaken out of the bundle, so there is no runtime cost unless you opt in. |
| 56 | |
| 57 | ## Notes |
| 58 | |
| 59 | - **Only built assets are precached.** Files emitted into the build are cached; remote or CDN-fetched assets are not available offline. To make remote images work offline, combine this with [Bundle Remote Assets](/features/bundle-remote-assets), which downloads them into the build. |
| 60 | - **No manifest icons.** An offline feature must not depend on a remote/CDN asset (and a deck's own [`favicon`](/custom/#headmatter) may be a URL), so the generated web app manifest intentionally ships no icons. It remains a valid manifest without them. |
| 61 | - **Large media.** Workbox's `maximumFileSizeToCacheInBytes` is raised to 100 MB and the precache glob covers common image, video, and audio extensions, so large media files are not silently skipped. |
| 62 | - **Video seeking offline.** Precached media is served as a full cached response, so playing from the start works offline; scrubbing/seeking through video may require additional range-request handling. |
| 63 |