Offline support

Page content:

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:

sh
npm i -D vite-plugin-pwa

Then turn it on:

postdoc.config.jsjs
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:

postdoc.config.jsjs
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.

Edit this page on GitHub