pwa-offline
Skill1 starsChanged 31 days agoMITView on GitHub
Use for service-worker strategy, the update flow, lazy-chunk-404 recovery after deploy, cache versioning, offline fallback, client storage, version skew across deploys, and the CDN/deploy headers that pin a broken worker. Fixes service-worker P-501..P-519, P-549, P-560..P-561; version-skew P-520..P-531; and build-deploy P-562, P-1101..P-1105. Trigger phrases: "users are stuck on the old version", "white screen after deploy", "service worker won''t update", "add offline support", "chunk 404 after release", "cache-first is serving stale HTML", "sw.js is cached by the CDN".
In this repository58 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- cf-cliSkill
- durable-objectsSkill
- game-gdd-authorSkill
- game-playtestSkill
- pmndrs-handleSkill
- pmndrs-pointer-eventsSkill
- pmndrs-uikitSkill
- prototype-fastSkill
- review-game-trailerSkill
- scenario-blender-expertSkill
- scenario-blender-retopologySkill
- scenario-blender-uv-bakingSkill
- threejs-perf-loadingSkill
- webapp-testingSkill
- workers-best-practicesSkill
- wranglerSkill
- xr-perceptual-constraints-displays-and-trackingSkill
- xr-platforms-audio-and-comfortSkill
- xr-referenceSkill
- xr-rendering-input-and-spatial-understandingSkill
- xr-ux-design-and-performance-budgetingSkill
- horizon-launch-roadmapSkill
- horizon-store-listing-assetsSkill
- horizon-web-store-publishSkill
- horizon-web-vrc-checklistSkill
- iwsdk-asset-pipelineSkill
- iwsdk-dev-workflowSkill
- iwsdk-performanceSkill
- iwsdk-project-setupSkill
- iwsdk-quest-device-testingSkill
- iwsdk-testingSkill
- iwsdk-vr-glassesSkill
- quest-browser-webxrSkill
- iwsdk-build-modelSkill
- iwsdk-compose-sceneSkill
- iwsdk-debugSkill
- iwsdk-depth-occlusionSkill
- iwsdk-devSkill
- iwsdk-grabSkill
- iwsdk-hostingSkill
- iwsdk-migrate-0-5Skill
- iwsdk-native-xr-testSkill
- iwsdk-physicsSkill
- iwsdk-pwa-packagingSkill
- iwsdk-raySkill
- iwsdk-uiSkill
- hz-immersive-designerSkill
- hz-iwsdk-webxrSkill
- hz-new-project-creationSkill
- hz-perfetto-debugSkill
- hz-quest-verify-firstSkill
- hz-simpleperf-debugSkill
- hz-store-pwaSkill
- hz-store-submitSkill
- hz-vr-debugSkill
- metavr-cliSkill
The file
Files
pwa-offline
The highest-stakes area: a wrong service worker can pin every user to a dead build with the fix itself trapped behind the cache. Covers service-worker entries (P-501..P-519, P-549, P-560..P-561), version skew (P-520..P-531), and build/deploy (P-562, P-1101..P-1105).
Audit first:
node "<pwa-audit-skill-dir>/scripts/run-audit.mjs" "<path-to-app>"Resolve <pwa-audit-skill-dir> from the selected pwa-audit/SKILL.md, not from the target
repository.
Static detection here classifies fetch-handler strategy and greps headers config — a
heuristic, not proof. The authoritative test is deploy A → deploy B on an existing
client (P-512): the single most valuable runtime test in the suite. The bundled
packages/deploy-harness proves the harness checks against its fixtures; it does not prove
an arbitrary repository. Require an explicit project deploy adapter or manual A→B evidence.
The one that ends companies: caching strategy
- P-502 — Network-first (or stale-while-revalidate with a fast timeout) for
request.mode === 'navigate'. Cache-first only for content-hashed immutable assets. Cache-first on HTML pins users to the old app forever and makes the fix un-shippable. - P-506 — never cache or serve cached responses for non-GET requests; branch on
request.method === 'GET'before any cache read/write. - P-507 — don't blanket-cache cross-origin
no-cors(opaque) responses — unknown status (a 404 caches happily) and padded quota. Scope caching to same-origin. - P-515 — preserve the original
credentialsmode when re-issuing requests, or installed users get random 401s. - P-516 — forward
Rangeheaders and return206for media, or Safari won't seek/play.
The update flow — and its two opposite mistakes
- P-503 — new SW sits in
waitingforever. Detectupdatefound→installedwith an existing controller → surface a non-blocking "Update available — reload", thenskipWaiting+clients.claimon user confirmation. - P-504 — the inverse, and agents love it as a "fix" for P-503:
skipWaiting()fired unconditionally swaps assets under a live tab → the running bundle requests chunks that no longer exist → white screen mid-session. Only after user-confirmed reload, or paired with a controlled reload oncontrollerchange. - P-505 — lazy chunk 404s after deploy (the most common real-world PWA outage). Ship a global dynamic-import error handler that force-reloads once (guarded against reload loops), plus a retention window for old chunks on the origin.
- P-512 — the update path is never tested. Ship the two-build harness: serve A, install, swap origin to B (delete A's hashed chunks), assert convergence.
Caching hygiene, offline, storage
- P-501 — a manifest alone is not a PWA; register a SW that actually controls the origin.
- P-508 — SW scope.
/static/sw.jscan only control/static/. Serve from the origin root or setService-Worker-Allowed. - P-509 — a precached offline document for failed navigations; enable
navigationPreload. - P-510 — versioned cache names + delete non-current caches on
activate. - P-511 — catch
QuotaExceededErroron Cache/IndexedDB writes; evict, surface a diagnostic. - P-513 — register the SW only in production (
NODE_ENV === 'production') and ship an unregister-and-clear escape hatch. A dev-active SW eats hours to stale output. - P-514 —
Cache-Control: no-cacheonsw.jsand the manifest. Long immutable TTLs only on hashed assets. A CDN that pins the worker means users can never receive the fix. - P-517 — IndexedDB for meaningful offline data, not
localStorage(~5MB, synchronous). Treat client storage as evictable for infrequently-used installs and browser tabs; request persistence where it matters. - P-518 — don't trust
navigator.onLine(reports "online" on captive portals); confirm with a real request. - P-519 — feature-detect Background/Periodic Sync (
'sync' in registration) with a foreground fallback. - P-549 — mobile notifications must use service-worker
registration.showNotification(), not page-contextnew Notification(). Coordinate the permission/subscription UX withpwa-push-permissions; keep one worker and test click focus/open behavior. - P-560 — generate precache URLs from the actual build output. One stale URL makes
atomic
cache.addAll()reject the entire install; surface that failure to telemetry. - P-561 — catch and report every
serviceWorker.register()rejection, and keep the worker path out of SPA catch-all rewrites so HTML is never served assw.js.
§5b — Version skew & stale client state
This is where "works on my clean profile, wedges every existing user" bugs live. P-521 is the keystone — without a client build stamp, nothing else here has anything to key off.
- P-521 — embed a build ID at build time, expose it (meta tag/global), send it with API requests.
- P-520 — version the auth-cookie name on any breaking change and explicitly clear the old one (or read both shapes for one release). A deliberate migration, never implicit — else existing clients wedge in a redirect loop.
- P-522 — version the API, or advertise a minimum supported client, so an old cached shell against a new API forces an update instead of a silent blank.
- P-523 — purge all user-scoped caches + IndexedDB + storage on logout and identity change. Retaining user A's data for user B on a shared device is a privacy incident, not a glitch.
- P-524 — cache names derive from the build ID;
activatedeletes every non-current cache (same pattern as P-510). - P-525 — version the persisted client schema; migrate or discard on read; wrap hydration in a fallback-to-clean path so build B doesn't white-screen on build A's stored state.
- P-526 — never cache responses to credentialed requests unless keyed by identity and purged on logout.
- P-527 — ship a reachable reset route that unregisters SWs, deletes caches, clears storage, reloads. The goal: support can fix a wedged user in one sentence.
- P-528 — the SW carries its build ID and declines to serve a mismatched shell; converge on one build.
- P-529 — set auth cookies server-side via
Set-Cookie; Safari ITP caps client-set (document.cookie) cookies at 7 days regardless ofmax-age, silently signing users out weekly. - P-530 —
Secure+ a deliberateSameSite/partitioning on auth cookies, tested through the real install → sign-in → relaunch path (standalone launch differs from the browser tab). - P-531 — distinguish optional from mandatory updates; a server-signalled minimum version triggers a forced reload. P-503's polite banner is wrong when the old client cannot work.
§11 — Build, deploy & platform config
- P-562 — hard-refresh representative deep routes and configure the repository's real
host to rewrite client-side routes to
index.htmlwithout rewritingsw.js, manifests, assets, APIs, or.well-knownendpoints. - P-1101 — on subpath deploys, set the build base path, manifest paths, and SW registration scope consistently to the real subpath (they break together otherwise).
- P-1102 —
Cache-Control: no-cacheonsw.js/manifest at the server/CDN layer (same as P-514, stated separately because it lives in config, not app code, and survives every app-side fix). - P-1103 — configure the framework PWA plugin (
next-pwa/vite-plugin-pwa) for the actual mode (App Router / static export / middleware); verify the precache manifest targets the real output dir. - P-1104 — run a Lighthouse/PWA installability audit in the release process and require a pass before calling PWA work done.
- P-1105 — publish a correct
.well-known/assetlinks.jsononly when shipping to Play via TWA (else the URL bar stays visible).
Standalone vs superpowers
Works standalone. When superpowers is available (detect by capability — is
test-driven-development invocable now? — never by path-sniffing):
test-driven-development— when a project adapter exists, the deploy-A→B harness is the failing test: run it against the current SW, watch it wedge/404, apply the strategy fix, watch it converge. The bundled fixture run is only harness self-conformance.verification-before-completion/pwa-verify— hard done-gate. §5 work is not done until the update-path test (P-512, P-1203) passes and the app has been tested offline (P-1204). A green build is not runtime evidence (P-1210).
Absent superpowers, run the two-build test by hand: build A, install (DevTools → Application → Service Workers), deploy B with A's chunks removed, reload, and assert the client reaches B with no stale HTML, no chunk 404, no reload loop. Then test airplane-mode navigation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

