Implement Progressive Web App features including service workers, caching strategies, offline support, and installation prompts for React and Svelte applications.
When to Use This Skill
Use this skill when:
- Adding PWA capabilities to a web app
- Implementing offline support
- Creating service worker caching strategies
- Debugging PWA installation issues
- Handling iOS-specific PWA quirks
Do NOT use this skill when:
- Building backend APIs
- Working on requirements/design (use those skills first)
- Need complex offline-first architecture (design first)
Core Principle
PWAs fail when offline behavior is an afterthought. A PWA is not "add service worker to existing app." It's a fundamental architectural decision about data flow, caching, and connectivity failure.
Diagnostic States
P0: No PWA Setup
Symptoms: No manifest.json, no service worker, online-only
Interventions:
- Run
scripts/manifest-generator.tsto create manifest - Add
<link rel="manifest">to HTML head - Generate minimal SW with
scripts/sw-scaffolder.ts
P1: Basic Manifest Only
Symptoms: Manifest exists but SW missing, breaks offline
Key Questions:
- What content MUST be available offline?
- What should always be fresh (network-first)?
Interventions:
- Use
scripts/cache-strategy-advisor.ts - Implement app shell pattern
- Add offline fallback page
P2: Caching Issues
Symptoms: Stale content, unexpected caching behavior
Interventions:
- Audit with
scripts/pwa-audit.ts - Map resources to strategies using
data/caching-strategies.json - Add cache expiration and cleanup
P3: Update Problems
Symptoms: Users stuck on old versions, multiple refreshes needed
Interventions:
- Implement skipWaiting/clients.claim appropriately
- Add update notification UI (
assets/update-prompt.tsx) - Handle "waiting" state properly
P4: Offline Data Gaps
Symptoms: User actions lost offline, no sync indicator
Interventions:
- Implement IndexedDB for offline storage
- Add Background Sync API
- Create sync status UI
P5: iOS Issues
Symptoms: Works on Android, breaks on iOS
Interventions:
- Review
data/ios-quirks.json - Add apple-mobile-web-app meta tags
- Handle storage eviction gracefully
P6: Production Ready
Indicators: Lighthouse PWA 100, works offline, updates cleanly
Caching Strategies
| Strategy | Use For | Behavior |
|---|---|---|
| Cache First | Static assets, fonts | Serve from cache, update in background |
| Network First | API data, user content | Try network, fall back to cache |
| Stale While Revalidate | Semi-static content | Serve stale, update cache for next time |
| Network Only | Auth, real-time data | Always network, no caching |
Available Scripts
| Script | Purpose |
|---|---|
manifest-generator.ts |
Generate manifest.json |
sw-scaffolder.ts |
Generate service worker |
cache-strategy-advisor.ts |
Recommend caching strategies |
pwa-audit.ts |
Validate PWA configuration |
Anti-Patterns
The Everything Cache
Precaching every asset - massive initial download. Fix: Precache only critical app shell. Runtime cache content.
The Immortal Cache
Never expiring caches - stale content forever. Fix: Cache versioning, delete old on activate, set max age.
The Silent Update
Forcing updates without notification. Fix: Notify user, let them choose when to refresh.
The iOS Afterthought
Building for Chrome, testing iOS last. Fix: Test iOS early. Accept iOS limitations.
Framework Quick Reference
React + Vite
npm i -D vite-plugin-pwa
SvelteKit
npm i -D @vite-pwa/sveltekit
Next.js
npm i next-pwa
See data/framework-patterns.json for configuration.
Debugging Checklist
- DevTools > Application > Manifest - Valid?
- DevTools > Application > Service Workers - Registered?
- DevTools > Application > Cache Storage - What's cached?
- DevTools > Network > Offline - Works offline?
- Lighthouse > PWA - Score and failures?
- iOS Safari - Test on actual device
Related Skills
- requirements-analysis - Determine offline requirements
- system-design - PWA architecture decisions
- react-pwa - React-specific PWA implementation