tomevault-io Progressive Web App Expert
Build installable, offline-capable web apps with Service Workers, smart caching, and native-like experiences.
When to Use This Skill
- Making a web app installable on mobile/desktop
- Implementing offline functionality
- Setting up Service Worker caching strategies
- Handling install prompts (
beforeinstallprompt) - Background sync for offline-first apps
- Managing PWA update flows
- Creating web app manifests
When NOT to Use This Skill
- Native app development → Use React Native, Flutter, or native SDKs
- General web performance → Use Lighthouse/performance auditing tools
- Server-side rendering issues → Use Next.js/framework-specific docs
- Push notifications only → Consider dedicated push notification services
- Simple static sites → PWA overhead may not be worth it
Core Concepts
What Makes a PWA Installable
- HTTPS (or localhost for dev)
- Web App Manifest with required fields
- Service Worker with fetch handler
- Icons (192×192 and 512×512 minimum)
The PWA Stack
┌─────────────────────────────────────────┐
│ Your App (React/Next.js) │
├─────────────────────────────────────────┤
│ Service Worker (sw.js) │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ Cache │ │ Network Fetch │ │
│ │ Storage │ │ Handling │ │
│ └─────────────┘ └─────────────────┘ │
├─────────────────────────────────────────┤
│ manifest.json │
│ (App identity, icons, display mode) │
└─────────────────────────────────────────┘
Web App Manifest
Complete manifest.json
{
"name": "Junkie Buds 4 Life",
"short_name": "JB4L",
"description": "Recovery support app",
"start_url": "/",
"scope": "/",
"display": "standalone",
"orientation": "portrait-primary",
"background_color": "#1a1410",
"theme_color": "#1a1410",
"icons": [
{
"src": "/icons/icon-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-maskable-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
],
"shortcuts": [
{
"name": "Find Meetings",
"short_name": "Meetings",
"url": "/meetings?source=shortcut",
"icons": [{ "src": "/icons/meetings-96.png", "sizes": "96x96" }]
}
]
}
Display Modes
| Mode | Description |
|---|---|
fullscreen |
No browser UI, full screen |
standalone |
App-like, no URL bar (recommended) |
minimal-ui |
Some browser controls |
browser |
Normal browser tab |
Link in HTML
<head>
<link rel="manifest" href="/manifest.json" />
<meta name="theme-color" content="#1a1410" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png" />
</head>
Service Worker Basics
Registration
// lib/pwa.ts
export async function registerServiceWorker() {
if ('serviceWorker' in navigator) {
try {
const registration = await navigator.serviceWorker.register('/sw.js', {
scope: '/',
});
return registration;
} catch (error) {
console.error('SW registration failed:', error);
}
}
}
// Call on app mount
useEffect(() => {
registerServiceWorker();
}, []);
Basic Service Worker Structure
// public/sw.js
const CACHE_NAME = 'myapp-v1';
const STATIC_ASSETS = ['/', '/offline', '/manifest.json'];
// Install: Cache static assets
self.addEventListener('install', (event) => {
event.waitUntil(
caches.open(CACHE_NAME).then((cache) => cache.addAll(STATIC_ASSETS))
);
self.skipWaiting();
});
// Activate: Clean old caches
self.addEventListener('activate', (event) => {
event.waitUntil(
caches.keys().then((keys) =>
Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
)
);
self.clients.claim();
});
// Fetch: Handle requests (see references for strategies)
self.addEventListener('fetch', (event) => {
event.respondWith(handleFetch(event.request));
});
See:
references/service-worker-patterns.mdfor caching strategy implementations
Caching Strategies
| Strategy | Best For | Tradeoff |
|---|---|---|
| Cache-First | Static assets, fonts, images | Stale until cache updated |
| Network-First | API data, user content | Slower, needs connectivity |
| Stale-While-Revalidate | Balance freshness/speed | Background updates |
| Network-Only | Auth, real-time data | No offline support |
| Cache-Only | Versioned assets | Never updates |
See:
references/service-worker-patterns.mdfor full implementations
Install Prompts
Handle the beforeinstallprompt event to show a custom install UI:
// Basic pattern
const [deferredPrompt, setDeferredPrompt] = useState(null);
useEffect(() => {
window.addEventListener('beforeinstallprompt', (e) => {
e.preventDefault();
setDeferredPrompt(e);
});
}, []);
const handleInstall = async () => {
if (deferredPrompt) {
deferredPrompt.prompt();
const { outcome } = await deferredPrompt.userChoice;
// outcome: 'accepted' or 'dismissed'
}
};
See:
references/install-prompt.mdfor fullusePWAInstallhook and component
Offline Experience
Key patterns:
- Offline page fallback for navigation failures
useOnlineStatushook to detect connectivity- Offline banner to inform users
See:
references/offline-handling.mdfor implementations
Background Sync
Queue actions while offline, execute when connectivity returns:
// In Service Worker
self.addEventListener('sync', (event) => {
if (event.tag === 'sync-data') {
event.waitUntil(syncPendingData());
}
});
// In App - trigger sync
const registration = await navigator.serviceWorker.ready;
await registration.sync.register('sync-data');
See:
references/background-sync.mdfor full IndexedDB integration
Update Flow
Notify users when a new version is available:
// Basic pattern
registration.addEventListener('updatefound', () => {
const newWorker = registration.installing;
newWorker?.addEventListener('statechange', () => {
if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
// New version available - show update prompt
}
});
});
See:
references/update-flow.mdforusePWAUpdatehook and update strategies
Next.js Integration
Options for Next.js PWA:
- next-pwa - Works with standard Next.js server
- Custom SW - Required for
output: 'export'(static sites) - Workbox CLI - Generate SW after build
See:
references/nextjs-integration.mdfor detailed configurations
Quick Reference
| Task | Solution |
|---|---|
| Check if installed | window.matchMedia('(display-mode: standalone)').matches |
| Force SW update | registration.update() |
| Clear all caches | caches.keys().then(keys => keys.forEach(k => caches.delete(k))) |
| Check online | navigator.onLine |
| Get SW registration | navigator.serviceWorker.ready |
| Skip waiting | self.skipWaiting() in SW |
| Take control | self.clients.claim() in SW |
Testing PWA
Chrome DevTools
- Application tab → Manifest, Service Workers, Cache Storage
- Lighthouse → PWA audit
- Network → Offline checkbox to simulate
Debug Checklist
- Manifest loads (Application → Manifest)
- SW registered (Application → Service Workers)
- Cache populated (Application → Cache Storage)
- Install prompt fires (Console for beforeinstallprompt)
- Offline page works (Network → Offline)
- Update flow works (trigger update, verify prompt)
References
Detailed implementations in /references/:
service-worker-patterns.md- Caching strategy implementationsinstall-prompt.md-usePWAInstallhook and install componentoffline-handling.md- Offline page, status hooks, bannersbackground-sync.md- Background sync with IndexedDBupdate-flow.md- Update detection and user promptsnextjs-integration.md- Next.js PWA configuration options
Converted and distributed by TomeVault — claim your Tome and manage your conversions.