PWA and Offline-First Service Workers

Pathrule2 Rules • 2 Memories • 1 Skill

A service worker is a separately updated network proxy that can outlive tabs, serve old assets, intercept navigation, queue mutations, and activate while several application versions are open at once. This pattern constrains cache ownership and mutation replay, records install and activation decisions, separates shell caching from application data, and supplies an update and offline-recovery test workflow. It complements CDN caching by focusing on browser-controlled caches and worker lifecycle, where the client can remain stale after the origin and edge are already correct.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

test-pwa-update-and-offline

src/

service-worker/

Cache only responses with an explicit ownership policy

Activation is a compatibility negotiation with open clients

Navigation fallback serves the application shell, not every failed request

offline/

Replay offline mutations with stable operation identity

Rules

Cache only responses with an explicit ownership policy/src/service-workerhighstrictClassify shell assets, public immutable data, private data, navigation, and errors before selecting a cache strategy.

1	A service worker sees credentials, redirects, partial responses, and failures that ordinary static caching guidance does not cover. A broad cache-first handler can persist user-specific or invalid content across sessions.
2
3	- Precache only build-owned immutable shell assets from a generated manifest; do not discover and cache arbitrary responses during install.
4	- Use separate named caches for shell, public runtime data, and other bounded classes so deletion and retention policies cannot erase unrelated content.
5	- Do not cache authenticated or user-specific responses unless the cache key and logout deletion contract isolate them by user and product policy explicitly permits storage.
6	- Reject non-success, opaque, partial, and unexpectedly redirected responses from cache insertion unless the endpoint has a reviewed reason to keep them.
7
8	See /src/offline for the adjacent decision or procedure that completes this constraint.

Replay offline mutations with stable operation identity/src/offlinehighstrictQueue only replay-safe commands, preserve user intent, and reconcile by idempotency key after reconnect or worker restart.

1	An offline client can submit the same queued command after browser restart, network ambiguity, or a failed acknowledgement. Without stable identity, one user action can create several orders, comments, or updates.
2
3	- Assign the logical action an idempotency key before local acceptance and store that key with the queued payload and actor context.
4	- Encrypt or avoid sensitive queued payloads according to the local-data policy, and remove them on sign-out or account removal.
5	- Replay in dependency order with bounded retry and a terminal conflict state; do not loop forever on validation, authorization, or obsolete commands.
6	- Reconcile the authoritative server result back into local state by operation identity and surface conflicts the product cannot merge automatically.
7
8	See /tests/pwa for the adjacent decision or procedure that completes this constraint.

Memories

Activation is a compatibility negotiation with open clients/src/service-workerLet the new worker wait unless the application can prove old tabs and new cached assets remain compatible.

1	Calling immediate activation feels like a fast update, but it can put a new network proxy underneath an old JavaScript bundle. Requests, routes, and cached schemas may no longer agree.
2
3	- Notify open clients that an update is waiting and let product policy choose a user prompt, safe reload point, or controlled mandatory refresh.
4	- Use immediate activation only when the shell, API, cache, and local-data contracts are backward compatible across the open-client window.
5	- Delete obsolete caches after activation with a version allowlist, while retaining assets still required by supported clients when compatibility demands it.
6	- After controller change, reload or reinitialize the application through one deliberate path instead of letting half the view continue with the prior bundle.
7
8	See /tests/pwa for the rule or workflow that puts this decision into practice.

Navigation fallback serves the application shell, not every failed request/src/service-workerApply shell fallback only to intended document navigations and preserve real errors for APIs, assets, and unsupported routes.

1	A catch-all fallback that returns HTML for a missing script, JSON endpoint, or image turns a clear network error into confusing parse and content failures elsewhere in the application.
2
3	- Check request mode, destination, method, and URL scope before using the application-shell fallback.
4	- Exclude API, authentication, upload, payment, callback, and asset routes from document fallback unless each has an explicit offline representation.
5	- Preserve server redirects and not-found behavior where the application does not own the route.
6	- Provide a bounded offline document for navigations that cannot use the shell, and make its retry behavior independent from a stale cached application.
7
8	See /src/offline for the rule or workflow that puts this decision into practice.

Skills

test-pwa-update-and-offline/rootExercise install, update, multi-tab activation, offline navigation, queued mutations, sign-out, and corrupted caches.

1	---
2	name: test-pwa-update-and-offline
3	description: Test a PWA or service-worker release under lifecycle and network failure conditions.
4	---
5
6	# Test Pwa Update And Offline
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	1. Install from a clean browser, load representative routes, then update while one old tab, one background tab, and one newly opened tab remain active.
11	2. Switch offline before and after install and verify shell, owned routes, excluded APIs, missing assets, and true not-found responses behave distinctly.
12	3. Queue mutations, terminate the tab or browser, reconnect, and prove replay uses stable identities and resolves conflicts without duplicate effects.
13	4. Sign out while private data and queued work exist, then confirm caches, storage, subscriptions, and replay permissions follow the privacy contract.
14	5. Corrupt or delete one cache generation and simulate a failed worker install; verify the previous working version remains usable and recovery does not require manual storage deletion.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often cache every response, delete old caches before old tabs stop using them, replay non-idempotent mutations, or force activation into an incompatible open client.

Built for Web teams building installable, resilient, or offline-capable applications.

Keeps your assistant from:

Serving private or error responses from a shared cache
Breaking an old open tab during worker activation
Duplicating mutations after reconnect and retry
Keeping a client permanently on an obsolete application shell

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25