Reference

Update dance

One page for “why is my new SW stuck waiting?” Source: Archibald lifecycle.

When the browser checks for updates

• Navigation to an in-scope page
• Functional events (e.g. push/sync) if no check in ~24h
• registration.update() if you call it (long-lived tabs)

New version = byte-different SW script (same URL). Do not version the SW filename for production updates.

Update path (default)

1. Browser fetches /sw.js (same URL).
2. Bytes differ → new worker gets its own install.
3. Install OK → new worker enters waiting (old still controls clients).
4. Waiting ends when old worker controls zero clients (close all tabs — refresh often not enough because of navigation overlap).
5. New worker activates → then controls new navigations.

skipWaiting

self.addEventListener("install", (event) => {
  self.skipWaiting(); // skip the waiting phase after install
  event.waitUntil(/* precache new cache name, e.g. static-v2 */);
});

• Activates as soon as install finishes (kicks out old active worker).
• Risk: pages loaded under old SW now get fetches from the new SW.
• Use when mixed versions are safe, or after an explicit user “Update now” message.

Cache versioning habit

// install: open static-v2, addAll(...)
// activate: delete caches not in expected list (e.g. drop static-v1)

Never overwrite the old cache name while the old SW still uses it. New name on install; delete old names on activate.

DevTools shortcuts

• Update on reload — install + skip wait each nav
• Skip waiting — promote waiting worker now
• Shift-reload — bypass SW for that load