PWA and Service Workers skill for Codex

Done well means: the app installs with correct icons and name, a deploy reaches users within one reload cycle without serving mixed old and new assets, offline users see cached content or a clear offline page (never the browser dinosaur), authenticated data is not leaked across users from caches, and there is a tested way to turn the service worker off.

Before changing anything

1. Read AGENTS.md, the build tool config and any existing manifest.*, sw.*, or registerSW code. Check navigator.serviceWorker usage with rg -n "serviceWorker|workbox|serwist|VitePWA" --glob '!node_modules'.
2. Confirm HTTPS in production (service workers need a secure context; localhost is exempt).
3. Ask what must work offline: app shell only, recently viewed content, or writes (queue and sync). That decides the caching plan. Do not cache everything by default.
4. Plugin installs need network; ask for approval in a sandbox.

Tooling

Stack	Default
Vite (React, Vue, Svelte, Solid)	vite-plugin-pwa (Workbox under the hood)
Next.js	Serwist (@serwist/next), the maintained successor to next-pwa
Nuxt	@vite-pwa/nuxt
SvelteKit	Built-in src/service-worker.js with $service-worker asset lists
Other / custom build	workbox-build (injectManifest) in a post-build step

Prefer injectManifest (you write the SW, the tool injects the precache list) once you need custom routes, push or sync. generateSW is fine for app-shell-only caching.

Manifest

{
  "id": "/",
  "name": "Field Notes",
  "short_name": "Notes",
  "start_url": "/?source=pwa",
  "scope": "/",
  "display": "standalone",
  "theme_color": "#0f172a",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ],
  "screenshots": [
    { "src": "/shots/wide.png", "sizes": "1280x800", "type": "image/png", "form_factor": "wide" },
    { "src": "/shots/narrow.png", "sizes": "750x1334", "type": "image/png" }
  ]
}

<link rel="manifest" href="/manifest.webmanifest">
<meta name="theme-color" content="#0f172a">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon-180.png">

Validate it with the bundled checker (run after build so --public points at served files):

node scripts/check_manifest.mjs dist/manifest.webmanifest --public dist

It fails on missing 192/512 icons, non-installable display, start_url outside scope, and icon files whose PNG dimensions do not match sizes; it warns on missing id, maskable icon, screenshots and colors.

• Set id once and never change it; it is the app’s identity for installed users.
• Maskable icons keep important art inside the central 80% safe zone; use a separate file, not "purpose": "any maskable".

Caching strategy per request type

Request	Strategy	Notes
Hashed build assets (JS, CSS, fonts)	Precache	Versioned by the build; served instantly
HTML navigations	Network-first with timeout (3 s) → cached page → offline fallback	Keeps content fresh; or precache the SPA shell
Images, avatars	Stale-while-revalidate or cache-first with expiration (max entries, max age)	Always cap entries
Public, slowly changing API (catalog)	Stale-while-revalidate	Show cached, refresh in background
Authenticated or personal API data	Network-only, or network-first into a per-user cache cleared on logout	Never shared caches
POST/PUT writes	Network-only + Background Sync queue if offline writes are required	Idempotency keys on the server
Third-party opaque responses	Avoid caching or cap tightly	Opaque responses count large against quota

Service worker (injectManifest, Workbox)

// src/sw.ts
/// <reference lib="webworker" />
import { precacheAndRoute, cleanupOutdatedCaches } from "workbox-precaching";
import { registerRoute, NavigationRoute, setCatchHandler } from "workbox-routing";
import { NetworkFirst, StaleWhileRevalidate } from "workbox-strategies";
import { ExpirationPlugin } from "workbox-expiration";
import * as navigationPreload from "workbox-navigation-preload";

declare const self: ServiceWorkerGlobalScope;

precacheAndRoute(self.__WB_MANIFEST);
cleanupOutdatedCaches();
navigationPreload.enable();

registerRoute(new NavigationRoute(new NetworkFirst({
  cacheName: "pages", networkTimeoutSeconds: 3,
})));

registerRoute(({ request }) => request.destination === "image",
  new StaleWhileRevalidate({
    cacheName: "images",
    plugins: [new ExpirationPlugin({ maxEntries: 120, maxAgeSeconds: 30 * 24 * 3600 })],
  }));

setCatchHandler(async ({ request }) =>
  request.destination === "document"
    ? (await caches.match("/offline.html")) ?? Response.error()
    : Response.error());

self.addEventListener("message", (e) => {
  if (e.data?.type === "SKIP_WAITING") self.skipWaiting();
});

Precache /offline.html (add it to the glob patterns) so the catch handler can serve it.

Updates without breaking sessions

1. New SW installs and waits while old tabs are open.
2. The page detects the waiting worker and shows “Update available, reload”.
3. On click, post SKIP_WAITING; on controllerchange, reload once.

import { registerSW } from "virtual:pwa-register";   // vite-plugin-pwa, registerType: "prompt"
const updateSW = registerSW({
  onNeedRefresh() { showToast("New version available", () => updateSW(true)); },
  onOfflineReady() { showToast("Ready to work offline"); },
});

• Calling skipWaiting() unconditionally on install can mix old HTML with new chunks and cause chunk-load errors mid-session. Use it only for SWs that serve nothing stateful.
• Serve sw.js with Cache-Control: no-cache so the browser checks for updates on every navigation; never cache the SW file at the CDN for long.
• Handle chunk-load failures in the router (reload once) as a safety net.

Push and background sync

• Web push needs a VAPID key pair, a server that stores subscriptions, and permission requested from a user gesture after explaining the value; never on page load. On iOS/iPadOS push works only for apps added to the Home Screen (16.4+).
• Sending pushes to real users is outward-facing: confirm with the user before triggering any test send outside a development subscription.
• Background Sync (workbox-background-sync BackgroundSyncPlugin) is Chromium-only; keep a foreground retry path for other browsers.

Kill switch

If a broken SW is in the wild, deploy a replacement at the same URL:

// sw.js — emergency unregister. Deploy only after the user confirms.
self.addEventListener("install", () => self.skipWaiting());
self.addEventListener("activate", async () => {
  for (const key of await caches.keys()) await caches.delete(key);
  await self.registration.unregister();
  for (const c of await self.clients.matchAll({ type: "window" })) c.navigate(c.url);
});

This deletes every cache for all users of the origin; confirm with the user before deploying. Clear-Site-Data: "cache", "storage" on a response is an alternative with wider blast radius.

Gotchas

• SW scope is its URL directory: /static/sw.js cannot control /. Serve it at the root or set Service-Worker-Allowed.
• Dev servers plus a registered SW serve stale code; enable “Update on reload” in DevTools Application panel, or disable the SW in development (devOptions.enabled: false).
• Caching responses with Set-Cookie or Vary: Cookie content into a shared cache leaks data between accounts on shared devices. Clear user caches on logout.
• Storage can be evicted; call navigator.storage.persist() only for apps where offline data matters, and check navigator.storage.estimate() against what you cache.
• Redirected navigation responses cannot be served from a SW for navigations in some browsers; cache the final URL.

Verification

• node scripts/check_manifest.mjs <built manifest> --public <dist> exits 0.
• DevTools Application panel: manifest has no errors, SW is activated and controls the page, caches contain only expected entries.
• Network set to Offline: reload key pages; cached ones load, others show the offline page.
• Deploy a second build locally: update prompt appears, reload switches cleanly, no chunk errors.
• Lighthouse PWA-related checks (installability) pass; install on Android Chrome and desktop Chrome; Add to Home Screen on iOS Safari shows correct name and icon.
• Log out and confirm per-user caches are deleted.

Output

Report: tool and mode (generateSW/injectManifest), manifest changes, the strategy per request type, update UX, offline fallback, push/sync status, and the kill-switch procedure.