PWA service worker doesn't auto-reload open tabs after a new build

[ashwin-pc]

Problem

The web UI does not update in browsers that have a long-lived open tab, even after dist/ is rebuilt and re-served. This is a service-worker caching issue, not a backend issue.

VitePWA (vite.config.ts) ships a service worker that precaches the app shell:

workbox: {
  navigateFallback: "/index.html",
  globPatterns: ["**/*.{js,css,html,svg,png,woff2}"], // precaches JS/CSS bundles
  ...
}

The SW intercepts requests and serves cached JS/CSS before hitting the server, so rebuilds don't reach those clients.

Why only some browsers

The generated registerSW.js is the minimal stub (from registerType: "autoUpdate"):

if('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js', { scope: '/' })
  })
}

It relies on skipWaiting + clientsClaim but has no reload-on-update logic, and the app never imports virtual:pwa-register. As a result:

1. The browser only checks for a new sw.js on a full navigation/reload (or ~every 24h). pi-web is a long-lived SPA tab, so tabs that are never reloaded never pick up a new SW.
2. Even when a new SW activates, the already-loaded page keeps running the old JS until reloaded — there is no controllerchange listener to force a refresh.

Recommended fix

Add auto-reload-on-update so clients get new code without manual intervention. Either:

• Add a one-time controllerchange listener that reloads:

  let refreshing = false;
  navigator.serviceWorker.addEventListener('controllerchange', () => {
    if (refreshing) return;
    refreshing = true;
    window.location.reload();
  });

• Or wire up virtual:pwa-register with registerSW({ immediate: true }) so vite-plugin-pwa's full auto-update flow runs instead of the minimal stub.

Workaround (already applied)

Per stuck browser: DevTools → Application → Service Workers → Unregister (or enable "Update on reload"), then hard reload. Or close all tabs of the app and reopen.

[ashwin-pc]

Fixed in src/app/sw-update.ts (new module) + src/main.ts.\n\nAdded a one-time controllerchange listener (initSwAutoReload()) that calls window.location.reload() whenever the service worker controller changes. Since the SW already uses skipWaiting + clientsClaim (via registerType: "autoUpdate"), the new SW activates immediately after install and the listener triggers a page reload — so long-lived tabs automatically pick up new builds without any manual intervention.

[ashwin-pc]

Still broken: dev mode ← production SW transition

The sw-update.ts fix handles production → production updates (new SW activates → controllerchange → reload). But it doesn't cover the case where:

1. A production build installed the SW (precaching index.html, JS/CSS bundles)
2. The server is later started in dev mode (e.g. npm run dev)
3. The old SW continues intercepting navigation requests and serving cached production assets
4. The new sw-update.ts listener never runs because the old cached JS doesn't contain it

This is a chicken-and-egg problem: you need the new code to run to detect the update, but the old SW prevents the new code from ever loading.

Why controllerchange doesn't help here

• No new SW is being installed (Vite dev mode doesn't generate sw.js)
• The old SW happily keeps serving from precache indefinitely
• Hard refresh / DevTools / Clear-Site-Data are the only escapes — none available in minimal browsers (e.g. embedded webviews, PWA standalone mode)

Fix: devSwKill Vite plugin

A small Vite plugin (apply: "serve") that intercepts /sw.js in dev mode and serves a self-destructing service worker:

function devSwKill(): Plugin {
  return {
    name: "dev-sw-kill",
    apply: "serve",
    configureServer(server) {
      server.middlewares.use((req, res, next) => {
        if (req.url === "/sw.js") {
          res.setHeader("content-type", "application/javascript");
          res.setHeader("cache-control", "no-cache, no-store, must-revalidate");
          res.end(`self.addEventListener('install', () => self.skipWaiting());
self.addEventListener('activate', (e) => {
  e.waitUntil(self.clients.claim().then(() => self.registration.unregister()));
});`);
          return;
        }
        next();
      });
    },
  };
}

The browser always fetches /sw.js from the network (SW scripts bypass the SW cache). On the next navigation, it detects the byte change, installs the self-destructing version, which then skipWaiting() → activate → unregister(). One more refresh and the page loads fresh from the dev server.

This should be reopened until the dev-mode case is addressed.

[ashwin-pc]

Reopening: the controllerchange auto-reload added here fixes long-lived desktop tabs, but it does not help installed iOS home-screen PWAs, which is where this bites hardest.

Root cause of the remaining gap: controllerchange only fires once the browser actually detects a new sw.js and the new SW takes control. Installed iOS PWAs do not reliably re-fetch sw.js on launch/resume, so the update is never detected — the app keeps serving the stale precached bundle (old assets/index-*.js) indefinitely. Symptom: shipped fixes simply never reach the device, even across full app reopens.

We hit this debugging an artifact-preview change (#28): the server clearly served the new bundle, but the device ran the old one for a long time.

Fix applied in src/app/sw-update.ts — explicitly trigger the update check rather than waiting for the browser:

navigator.serviceWorker.ready.then((registration) => {
  const check = () => { registration.update().catch(() => undefined); };
  check();                                   // on load
  document.addEventListener("visibilitychange", () => {
    if (document.visibilityState === "visible") check();
  });
  window.addEventListener("focus", check);   // on regaining focus
  window.setInterval(check, 60 * 60 * 1000); // hourly
});

The existing controllerchange handler then reloads once the freshly-fetched SW activates.

Note: this fix lives in the new bundle, so a device stuck on the old SW needs one manual reset to adopt it (delete + re-add the home-screen icon, or clear site data in Safari). After that, updates land on their own.

Separately, while here we also found the SW's navigateFallback: "/index.html" had no navigateFallbackDenylist, so navigations to /api/artifacts/*.html were served the app shell instead of the real artifact. Filing/looping that separately — mentioning here since both are SW/workbox config issues in vite.config.ts.