Installable web apps and offline behavior

PWA Essentials

Start from what exists

• Find the current setup: vite-plugin-pwa, next-pwa, @angular/service-worker, a Workbox config or a hand-written sw.js. Extend it; never add a second service worker.
• A generated service worker is configured, not edited: change the plugin options or its injectManifest source.

Manifest

• Link it from every page: <link rel="manifest" href="/manifest.webmanifest">.
• Fields: name, short_name, id, start_url, scope, display (standalone), background_color, theme_color, icons.
• Icons: 192x192 and 512x512 PNG minimum, plus a 512 maskable icon with safe-zone padding. Paths resolve relative to the manifest.
• Add <meta name="theme-color"> matching the manifest.

Service worker

• Register after load from the app entry, in production builds only unless the repo does otherwise. Handle registration errors.
• Scope is the folder the SW is served from; serve it from the root to control the whole app.
• Serve the SW file with no-cache headers so updates are found. HTTPS is required (localhost is exempt).

Caching strategies

• Precache the app shell (entry HTML, hashed JS/CSS, core icons) with a build-generated manifest and revisions.
• API and dynamic data: network-first with a timeout and cache fallback, or network-only for user-specific or sensitive data.
• Static assets, images, fonts: stale-while-revalidate, or cache-first with expiration (max entries, max age).
• Never cache authenticated responses, POST requests or error responses.
• Version cache names; delete old caches in the activate event.

Updates

• Do not call skipWaiting unconditionally on install in stateful apps; it can mix old pages with new assets.
• Preferred flow: new SW installs and waits, the page shows an update prompt, on confirm post SKIP_WAITING, reload on controllerchange. With vite-plugin-pwa use registerType prompt and onNeedRefresh / useRegisterSW.
• Each deploy must change asset hashes or revisions so the update is detected.

Offline

• Precache an offline fallback page and serve it for failed navigations.
• Show offline state in the UI; queue or disable writes instead of failing silently (Workbox background sync where supported).

iOS quirks

• Add apple-touch-icon (180x180) and the apple-mobile-web-app meta tags; iOS may ignore manifest icons.
• iOS has no beforeinstallprompt: show manual Add to Home Screen instructions instead of an install button.
• Storage can be evicted and background sync is unavailable; web push works only for installed apps on recent iOS.
• Handle safe areas with viewport-fit=cover and env(safe-area-inset-*).

Before you finish

• Manifest valid, with 192, 512 and maskable icons.
• Service worker registers with the intended scope; the SW file is not cached.
• A caching strategy per request type; no authenticated data cached.
• Update flow tested: a new build is detected and applied cleanly.
• Offline fallback works (DevTools offline, then reload).
• Installability checked in DevTools Application panel or Lighthouse on a production build.