---
name: pwa-engineering
description: Design, build, audit, debug, and verify production Progressive Web Apps across frameworks. Use for web app manifests, service workers, offline behavior, installability, update flows, cache strategy, push notifications, background capabilities, iOS or Android PWA behavior, Lighthouse findings, and regressions caused by stale cached assets.
---

# PWA Engineering

Build PWAs as resilient web applications, not as a checklist of install badges. Start with the product's real offline, update, security, and data-consistency requirements, then choose the smallest platform features that meet them.

## Operating principles

- Inspect the existing framework, build output, hosting headers, router, authentication model, and deployment topology before changing code.
- Treat browser support and install criteria as time-sensitive. Verify current primary documentation when a result depends on a specific browser or operating-system version.
- Preserve normal web behavior. A failed service worker, denied notification permission, or unavailable background API must not make the application unusable.
- Never cache credentials, authorization responses, private user data, payment flows, mutation requests, or opaque third-party responses without an explicit reviewed policy.
- Prefer framework-supported PWA integration or Workbox when it fits the stack. Write a custom service worker only when its lifecycle and caching behavior remain easier to reason about than the abstraction.
- Make update behavior visible and recoverable. Do not silently strand clients on incompatible HTML, JavaScript, or API versions.

## Workflow

1. Define the target experience: installable shell, offline reading, offline mutation queue, push, background work, or only resilient repeat visits. Record which browsers and devices matter.
2. Inspect the current manifest, service-worker registration, generated assets, navigation routing, HTTPS setup, response headers, and deployment cache headers.
3. Run `scripts/manifest_preflight.py` against the manifest. Treat warnings as review prompts rather than universal installability rules.
4. Build a request-by-request cache matrix before editing the service worker:

   | Request class | Typical strategy | Important boundary |
   | --- | --- | --- |
   | Versioned static assets | Cache first | Change the URL when content changes |
   | HTML navigation | Network first or app-shell fallback | Do not serve incompatible stale HTML indefinitely |
   | Public read-only API | Network first or stale-while-revalidate | Define freshness and offline semantics |
   | Authenticated API | Usually network only | Cache only after explicit privacy review |
   | Mutations | Network with explicit queue | Require idempotency and conflict handling |
   | Images/media | Cache first with limits | Enforce quota, expiry, and eviction |

5. Implement install metadata: stable `id`, appropriate `start_url` and `scope`, names, display mode, colors, and purpose-built icons. Keep the manifest same-origin unless the platform explicitly supports the chosen setup.
6. Implement the service-worker lifecycle deliberately: version caches, remove only caches owned by this application, activate updates predictably, and coordinate `skipWaiting` or client reloads with the UI.
7. Add an offline state that explains what is available and what requires connectivity. Queue mutations only when the server contract supports idempotency, replay, ordering, and conflict resolution.
8. Add install and notification prompts only in response to clear user value. Request notification permission from an intentional user action, never on initial page load.
9. Test first load, repeat load, offline navigation, expired caches, update from the previous deployed version, multi-tab behavior, storage pressure, authentication changes, and uninstall/reinstall.
10. Verify on real target devices. Desktop emulation does not prove iOS standalone behavior, Android install behavior, push delivery, safe areas, or OS-level lifecycle handling.

## Service-worker review checklist

- Registration URL and scope cover the intended routes and no more.
- The service worker is served with JavaScript content type, without redirects, over HTTPS except for localhost development.
- Install failures do not leave partially populated caches treated as valid.
- Fetch handlers call `respondWith` synchronously and return valid responses for every handled branch.
- Navigation fallback never intercepts APIs, authentication callbacks, files, or unrelated origins.
- Cache names are application-owned and versioned; activation does not delete caches owned by other apps.
- Cached responses have explicit freshness and size policies.
- Update prompts preserve unsaved user work and avoid reload loops across multiple tabs.
- Logout and account switching clear or partition user-sensitive state.
- Telemetry can distinguish online, offline, cache-hit, update, and replay failures without logging private data.

## Verification

Use a clean browser profile for installation checks. Verify at minimum:

1. Manifest parses and its referenced icons resolve.
2. Service worker installs, activates, controls the intended pages, and reports no console errors.
3. The app starts from its installed icon at the expected route and display mode.
4. A controlled offline test matches the documented offline contract.
5. Deploying a new version upgrades an already-open and an already-installed client safely.
6. Accessibility remains intact in standalone mode: focus, keyboard, reduced motion, contrast, zoom, safe areas, and orientation changes.
7. Server headers do not cache the service-worker script or HTML longer than the update design permits.

Read [references/official-sources.md](references/official-sources.md) before making claims about current browser support or install requirements.

## Report format

Return:

1. Target experience and supported platforms.
2. Observed architecture and evidence.
3. Findings ordered by user impact and data risk.
4. Minimal proposed changes with cache and update semantics.
5. Tests run and results.
6. Remaining device-specific checks and rollback plan.