Skip to content

PWA shell

Make the web app installable and keep its shell available offline with one pwa option. Pass the same object to runProdApp and to the dev server (runDevApp or createKumikoServer); without it nothing changes and no service worker is registered.

  • Manifest: GET /manifest.webmanifest is built from name, shortName, themeColor, backgroundColor and icons (display: standalone, scope /). /manifest.json stays the hashed-asset map that kumiko build writes.

  • Head tags: every HTML shell gets the manifest link, theme-color, the Apple home-screen tags, an apple-touch-icon (largest icon that is not maskable) and <meta name="kumiko-pwa-sw">. The web client registers the worker only when that meta is present.

  • Service worker: GET /sw.js is generated by the server, no build step and no external library. It precaches /, the manifest, the icons and the hashed bundles, serves /assets/* cache-first, goes to the network first for navigations and falls back to the cached shell only when offline. /api/, /sse/, /auth/, SSE streams, non-GET and cross-origin requests never touch the cache. A new build gets a new cache name and the old cache is dropped on activate.

  • Install hint: a one-time banner. iOS explains Share and “Add to Home Screen”, other browsers get an Install button behind beforeinstallprompt. “Not now” is remembered in localStorage; standalone launches never show it.

  • Base path: an app mounted below the origin root (for example veridom.de/a) sets basePath: "/a/". Only the shell, manifest and worker live under it: the manifest and worker are served at /a/manifest.webmanifest and /a/sw.js, start_url, scope, the shell precache and the offline fallback use /a/, and the client registers the worker with the scope of its directory. A worker can only control its own directory, so it must live under the base path. /assets/* and the API paths (/api, /sse, /auth) stay at the origin root, so the ingress must route them to the app as well (for example /a, /api and /assets on veridom.de). Each base path gets its own cache name prefix, so apps on one origin do not delete each other’s precache. The boot rejects a base path that does not start and end with /, has an empty, . or .. segment, or contains ? or #.

Icons must be same-origin paths (/icons/...) served from public/ in dev and dist/ in production; the boot rejects anything else. The default CSP (default-src 'self') already allows the manifest and the worker.

  1. src/app.ts defines the feature and the pwa option.
  2. bin/server.ts passes both to runProdApp with staticDir: "dist".
  3. The test boots the dev server with the same option and checks the shell tags, the manifest and the generated worker over HTTP.
Terminal window
bun kumiko test all samples/recipes/pwa-shell/

📄 On GitHub: samples/recipes/pwa-shell