Build Offline-Capable Web Apps with Service Workers

Walks through building a complete, installable, offline-capable Progressive Web App from three required pillars: HTTPS (required in production for service workers to register; localhost is exempt for development), a Web App Manifest (manifest.json, making the app installable and defining its home-screen appearance), and a Service Worker (sw.js, a background script that intercepts network requests, manages caches, and enables offline functionality). It specifies five minimum deliverable files - index.html (links the manifest, registers the service worker), manifest.json, sw.js (with install, activate, and fetch handlers), app.js (service-worker registration plus install-prompt handling), and offline.html (the fallback page shown when navigation fails offline - a required file, since a missing one causes install to fail). The service worker implements versioned caching (an incrementing CACHE_VERSION string that must bump on every deploy so activate clears stale caches), pre-caches an app-shell of core files on install, and picks a caching strategy per resource type on fetch: cache-first for static assets, network-first for HTML pages (falling back to the cached page or offline.html), and stale-while-revalidate for API data under /api/.

Use it when a web app needs to work offline or on unreliable networks, when building a mobile-first project where users should be able to install the app to their home screen, when the user asks about caching strategies, service workers, or improving web app resilience, when Workbox, web app manifests, background sync, or push notifications for the web come up, or when a user asks "can my website be installed like an app?" or "how do I make my site work offline?" without using the word PWA. Platform caveats to respect: Safari supports manifests and service workers but not the beforeinstallprompt event, so iOS users must install manually via the Share menu's "Add to Home Screen" option, and Safari may clear service-worker caches after roughly 7 days of inactivity under Intelligent Tracking Prevention; cross-origin requests (CDN fonts, third-party APIs) return "opaque" responses that report status 200 even on failure, so they should be cached cautiously, preferably with stale-while-revalidate or via Workbox. Before shipping, verify HTTPS is live, the manifest has name/short_name/start_url/display/both icon sizes with purpose: "any maskable", the service worker registers cleanly in DevTools, the app shell loads under simulated offline conditions, the Lighthouse PWA audit passes, and the install flow has actually been tested on both iOS Safari and Android Chrome.

Input is the app's static assets and API routes; output is an installable, offline-tolerant web app. A minimal manifest:

{
  "name": "My Awesome PWA",
  "short_name": "MyPWA",
  "description": "A fast, offline-capable Progressive Web App.",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait-primary",
  "background_color": "#ffffff",
  "theme_color": "#0055ff",
  "icons": [
    {
      "src": "/assets/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/assets/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ]
}

display: "standalone" hides browser UI (versus minimal-ui or plain browser); purpose: "maskable" enables adaptive icons on Android, provided the visible content stays inside the icon's center 80% safe zone. Optional screenshots entries unlock Chrome's enhanced desktop install dialog.

Works with the native browser Service Worker and Cache Storage APIs directly, or with Workbox (Google's PWA library, loadable via CDN or npm) for production apps that want cache expiry, versioning, and edge cases like opaque cross-origin responses handled automatically rather than hand-rolled. Recommends mkcert or ngrok for local HTTPS when testing service workers outside localhost, and Chrome DevTools' Lighthouse tab for the final PWA audit.

Web developers adding installability and offline resilience to an existing site or building a mobile-first web app from scratch, who need the manifest, service worker, and caching-strategy pieces wired together correctly rather than assembled from scattered documentation.