PWAs and service workers

01The idea: a website that behaves like an app

A PWA is not a new technology but a set of browser features used together. Over HTTPS, a site with a valid manifest can be installed to the home screen or desktop, launch in a standalone window without browser chrome, and appear in the app switcher. A service worker adds offline support, faster loading through caching, and optionally push notifications and background tasks. Think of the service worker as a smart doorman: every request the page makes passes through it, and it decides whether to fetch from the network, answer from its cache, or both. 'Progressive' means it degrades gracefully: browsers that do not support a feature still get a normal website.

• Requires HTTPS (localhost is allowed for development).
• Manifest: identity and appearance when installed.
• Service worker: network proxy, cache and background work.

02The web app manifest

The manifest is a JSON file linked from the page. Key fields: name and short_name (shown under the icon), start_url (where the app opens), scope (which URLs belong to the app), display (standalone for an app window), theme_color and background_color (title bar and splash screen), and icons. Provide at least 192x192 and 512x512 PNG icons. Maskable icons, marked with purpose 'maskable', have their important content inside a central safe zone (a circle of 80% of the width), so Android can crop them to circles, squircles or other shapes without cutting off the logo. Add an id so the browser can identify the app even if start_url changes, and screenshots plus description for a richer install dialog.

1{
2  "id": "/",
3  "name": "Example Portfolio",
4  "short_name": "Portfolio",
5  "start_url": "/?source=pwa",
6  "scope": "/",
7  "display": "standalone",
8  "theme_color": "#0f172a",
9  "background_color": "#0f172a",
10  "icons": [
11    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
12    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
13    { "src": "/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
14  ]
15}

03The service worker lifecycle

A service worker is a JavaScript file that runs in its own thread, without access to the DOM, and can outlive the page. The page registers it; the browser downloads it and fires install, where you typically pre-cache the offline page and core assets. Then it waits until no open tabs use the old worker, and fires activate, where you delete old caches. From then on it receives fetch events for every request within its scope. When you deploy a changed worker file, the browser detects the byte difference, installs the new version, and keeps it waiting until old tabs close. skipWaiting() and clients.claim() make a new version take over immediately, which is convenient but can mix old pages with new cached assets, so use them deliberately.

1// In the page (only in production builds)
2if ("serviceWorker" in navigator) {
3  window.addEventListener("load", () => {
4    navigator.serviceWorker.register("/sw.js", { scope: "/" })
5      .catch((err) => console.error("SW registration failed", err));
6  });
7}

04Caching strategies

Inside the fetch handler you choose a strategy per kind of request. Cache-first serves from cache and only goes to the network on a miss; ideal for fingerprinted static assets (app.3f9a.js) and fonts that never change. Network-first tries the network and falls back to cache when offline; ideal for HTML pages and API data that should be fresh. Stale-while-revalidate answers instantly from cache and refreshes the cache in the background; good for avatars and non-critical data. Network-only is for things that must never be cached, like authenticated mutations and payments. A common, safe default for content sites is network-first for navigations with an offline fallback page, and cache-first for hashed static files.

• Cache-first: hashed JS/CSS, fonts, icons.
• Network-first: HTML navigations, fresh API reads.
• Stale-while-revalidate: images, non-critical JSON.
• Network-only: POST requests, auth, checkout.

05A network-first service worker with an offline page

This hand-written worker pre-caches an offline page on install, removes old caches on activate, and handles page navigations network-first: it tries the network, stores a copy of successful pages, and falls back to the cached page or the offline page when the network fails. Non-GET requests and other origins are left alone. Bump the cache version when the offline page or core files change.

1const CACHE = "site-v3";
2const OFFLINE_URL = "/offline";
3 
4self.addEventListener("install", (e) => {
5  e.waitUntil(caches.open(CACHE).then((c) => c.addAll([OFFLINE_URL, "/icons/icon-192.png"])));
6});
7self.addEventListener("activate", (e) => {
8  e.waitUntil(caches.keys().then((keys) =>
9    Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k)))));
10});
11self.addEventListener("fetch", (e) => {
12  const req = e.request;
13  if (req.method !== "GET" || new URL(req.url).origin !== location.origin) return;
14  if (req.mode !== "navigate") return;
15  e.respondWith(fetch(req).then((res) => {
16    const copy = res.clone();
17    if (res.ok) caches.open(CACHE).then((c) => c.put(req, copy));
18    return res;
19  }).catch(async () => (await caches.match(req)) || caches.match(OFFLINE_URL)));
20});

06PWAs in Next.js

Next.js App Router has first-class support for the manifest: an app/manifest.ts file returning a MetadataRoute.Manifest object is served as /manifest.webmanifest and linked automatically. Theme colour goes into the viewport export. The service worker is a static file in public/sw.js, served from the site root so its scope covers the whole app, and registered from a small client component. Add an offline route (app/offline/page.tsx) that does not depend on data so it can be pre-cached. Serve sw.js with Cache-Control: no-cache so browsers check for updates promptly; the Next.js docs show this via headers() in next.config. For larger apps, Serwist (the maintained successor of next-pwa, built on Workbox ideas) generates precache manifests from the build.

1// app/manifest.ts
2import type { MetadataRoute } from "next";
3 
4export default function manifest(): MetadataRoute.Manifest {
5  return {
6    name: "Example Portfolio",
7    short_name: "Portfolio",
8    start_url: "/",
9    display: "standalone",
10    background_color: "#0f172a",
11    theme_color: "#0f172a",
12    icons: [
13      { src: "/icons/icon-192.png", sizes: "192x192", type: "image/png" },
14      { src: "/icons/icon-512.png", sizes: "512x512", type: "image/png" },
15      { src: "/icons/maskable-512.png", sizes: "512x512", type: "image/png", purpose: "maskable" },
16    ],
17  };
18}

07Install, push and platform differences

Chromium browsers (Chrome, Edge, Samsung Internet) show an install prompt or menu entry when the site is on HTTPS and has a manifest with name, icons, start_url and a suitable display mode; you can capture the beforeinstallprompt event to show your own install button. Safari on iOS and iPadOS installs through Share, then Add to Home Screen, and since iOS 16.4 installed web apps can receive Web Push. Safari on macOS supports Add to Dock. Push needs a service worker, user permission requested after a user gesture, VAPID keys and a server that sends messages. Background Sync and Periodic Background Sync are Chromium-only, so treat them as enhancements. Firefox desktop does not install PWAs natively. Test on every target platform.

08Scope, navigation preload and performance

A service worker controls pages within its scope, which by default is the directory it is served from; that is why sw.js lives at the root. A page is only controlled after the worker activates, so the very first visit is never intercepted unless you call clients.claim(). One hidden cost of network-first is startup: when the worker is idle, the browser must boot it before the request can go out, adding tens of milliseconds. Navigation preload fixes this: the browser starts the navigation request in parallel with booting the worker, and the fetch handler uses event.preloadResponse. Keep the fetch handler fast and avoid an empty fetch listener, which adds overhead without benefit.

1self.addEventListener("activate", (e) => {
2  e.waitUntil(self.registration.navigationPreload?.enable());
3});
4 
5self.addEventListener("fetch", (e) => {
6  if (e.request.mode !== "navigate") return;
7  e.respondWith((async () => {
8    try {
9      return (await e.preloadResponse) || (await fetch(e.request));
10    } catch {
11      return (await caches.match(e.request)) || caches.match("/offline");
12    }
13  })());
14});

09Safe update flows

The safest update pattern is: the new worker installs and waits; the page listens for a waiting worker and shows a 'new version available' banner; when the user accepts, the page posts a message, the worker calls skipWaiting(), and the page reloads on controllerchange. This avoids a running page suddenly being served by a worker whose cache holds different asset versions. For a content site with network-first HTML and hashed assets, automatic skipWaiting is usually fine, because old assets are not deleted mid-session if you keep the previous cache for a while. Always include a kill switch: deploying a worker that unregisters itself and clears caches is the emergency recovery if a bad worker ships.

1// Emergency "kill switch" sw.js
2self.addEventListener("install", () => self.skipWaiting());
3self.addEventListener("activate", (e) => {
4  e.waitUntil((async () => {
5    for (const key of await caches.keys()) await caches.delete(key);
6    await self.registration.unregister();
7    for (const c of await self.clients.matchAll()) c.navigate(c.url);
8  })());
9});

10Storage limits, eviction and offline data

The Cache API, IndexedDB and other origin storage share a quota managed by the browser; Chromium allows an origin up to a large fraction of free disk, Safari is stricter and may evict storage of sites not used for a while. By default storage is 'best effort' and can be cleared under pressure; navigator.storage.persist() requests persistent storage, which browsers grant based on engagement or installation. Check usage with navigator.storage.estimate(). For offline data beyond cached responses, such as drafts or queued form submissions, use IndexedDB (through a small wrapper like idb), and replay queued requests when back online, with Background Sync on Chromium and an online event fallback elsewhere. Design for conflicts: queued writes can be stale by the time they reach the server.

11Security and privacy pitfalls

Service workers are powerful, so browsers require HTTPS and same-origin scripts. The main risks are self-inflicted. Caching responses keyed only by URL can store one user's personalised page and show it to the next user on a shared device; never cache authenticated HTML or API responses in a generic cache, and clear caches on logout. Cross-origin opaque responses (no-cors) count heavily against quota and cannot be inspected for errors, so avoid caching them. An XSS bug that can register a worker would persist an attacker's code, so a strict Content Security Policy and worker-src directive help. Finally, a broken worker can lock users out of updates, which is why short HTTP caching on sw.js and a kill switch matter.