Offline support
Postdoc can build your site as a progressive web app: a service worker stores the site in the browser on the first visit, and from then on pages load from the browser's cache and keep working without a network connection. It's off by default.
Turn it on
The service worker comes from vite-plugin-pwa, which a project installs when it wants one:
npm i -D vite-plugin-pwaThen turn it on:
export default {
pwa: {
enabled: true
}
};The next build adds a service worker, sw.js, a web app manifest and a small script that registers the worker on every page. On a reader's first visit, the service worker downloads the site's pages, styles, scripts, images and fonts in the background.
When you deploy a new version, the service worker picks up the changes in the background.
What is stored
By default, the service worker stores files of these types: HTML, CSS, JavaScript, JSON, PNG, JPEG, ICO, WebP, AVIF, SVG and WOFF2. Files over 2 MB make the build fail, and it lists them. To leave them out of the cache instead, set showMaximumFileSizeToCacheInBytesWarning: true in pwa.
Some things still need a connection:
- Search. The search index is written after the service worker is generated, so it isn't stored.
- Mermaid diagrams. The default theme loads Mermaid from a CDN.
- Files of other types, such as PDFs or videos, and files over the size limit.
A URL that isn't part of the site isn't answered from the cache, so readers get your 404 page or the browser's offline message, not a wrong page.
Settings
Postdoc uses vite-plugin-pwa, and passes the pwa settings to it, so all of its options work here. For example, to name the installed app and store larger files:
export default {
pwa: {
enabled: true,
manifest: {
name: 'Acme Docs',
short_name: 'Acme',
theme_color: '#1e392e'
},
workbox: {
maximumFileSizeToCacheInBytes: 5 * 1024 * 1024
}
}
};Setting workbox.globPatterns replaces the default list of file types.
To let readers install the site as an app, the manifest also needs icons. The vite-plugin-pwa guide lists what's required.