pwa-development

PWA Development

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.ts to 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

1. DevTools > Application > Manifest - Valid?
2. DevTools > Application > Service Workers - Registered?
3. DevTools > Application > Cache Storage - What's cached?
4. DevTools > Network > Offline - Works offline?
5. Lighthouse > PWA - Score and failures?
6. iOS Safari - Test on actual device

Related Skills

• requirements-analysis - Determine offline requirements
• system-design - PWA architecture decisions
• react-pwa - React-specific PWA implementation