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.
What it shows
Section titled “What it shows”-
Manifest:
GET /manifest.webmanifestis built fromname,shortName,themeColor,backgroundColorandicons(display: standalone, scope/)./manifest.jsonstays the hashed-asset map thatkumiko buildwrites. -
Head tags: every HTML shell gets the manifest link,
theme-color, the Apple home-screen tags, anapple-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.jsis 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 inlocalStorage; standalone launches never show it. -
Base path: an app mounted below the origin root (for example
veridom.de/a) setsbasePath: "/a/". Only the shell, manifest and worker live under it: the manifest and worker are served at/a/manifest.webmanifestand/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,/apiand/assetson 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.
src/app.tsdefines the feature and thepwaoption.bin/server.tspasses both torunProdAppwithstaticDir: "dist".- The test boots the dev server with the same option and checks the shell tags, the manifest and the generated worker over HTTP.
bun kumiko test all samples/recipes/pwa-shell/Source
Section titled “Source”📄 On GitHub: samples/recipes/pwa-shell