pwa-development · jwynia — Claude Code skill: PWA, service worker, offline

---
name: pwa-development
description: "Implement Progressive Web App features for React and Svelte projects. This skill should be used when the user asks to 'make a PWA', 'add offline support', 'create a service worker', 'fix caching issues', or wants installable web apps. Keywords: PWA, service worker, offline, manifest, caching, installable, Workbox, vite-pwa."
license: MIT
compatibility: Works with React, Svelte/SvelteKit, Vite, Next.js.
metadata:
  author: jwynia
  version: "1.0"
  type: utility
  mode: assistive
  domain: 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
```bash
npm i -D vite-plugin-pwa
```

### SvelteKit
```bash
npm i -D @vite-pwa/sveltekit
```

### Next.js
```bash
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