Push notifications are blocked. Enable them in browser settings.
return (
)
}
```
### Server: subscribe endpoint (`app/api/push/subscribe/route.ts`)
```ts
import { NextRequest, NextResponse } from 'next/server'
import webpush from 'web-push'
webpush.setVapidDetails(
process.env.VAPID_SUBJECT!,
process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
process.env.VAPID_PRIVATE_KEY!
)
export async function POST(req: NextRequest) {
const subscription: PushSubscription = await req.json()
// Save subscription to your database
// await db.pushSubscriptions.upsert({ endpoint: subscription.endpoint, subscription })
return NextResponse.json({ success: true })
}
```
### Server: send notification (`app/api/push/send/route.ts`)
```ts
import { NextRequest, NextResponse } from 'next/server'
import webpush from 'web-push'
webpush.setVapidDetails(
process.env.VAPID_SUBJECT!,
process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
process.env.VAPID_PRIVATE_KEY!
)
export async function POST(req: NextRequest) {
const { title, body, url } = await req.json()
// Fetch all subscriptions from your database
// const subscriptions = await db.pushSubscriptions.findAll()
const payload = JSON.stringify({ title, body, url, icon: '/icons/icon-192x192.png' })
const results = await Promise.allSettled(
subscriptions.map((sub) => webpush.sendNotification(sub.subscription, payload))
)
const failed = results.filter((r) => r.status === 'rejected')
// Remove invalid subscriptions (410 Gone = user unsubscribed)
// await db.pushSubscriptions.deleteMany(failed.map(f => f.endpoint))
return NextResponse.json({ sent: results.length - failed.length, failed: failed.length })
}
```
### Service worker: handle push event
```js
// Add to your custom SW file (public/sw-custom.js or swSrc)
self.addEventListener('push', (event) => {
const data = event.data?.json() ?? {}
const { title = 'MyApp', body = '', url = '/', icon = '/icons/icon-192x192.png' } = data
event.waitUntil(
self.registration.showNotification(title, {
body,
icon,
badge: '/icons/badge-72x72.png',
data: { url },
actions: [
{ action: 'open', title: 'Open' },
{ action: 'dismiss', title: 'Dismiss' },
],
vibrate: [200, 100, 200],
})
)
})
self.addEventListener('notificationclick', (event) => {
event.notification.close()
if (event.action === 'dismiss') return
const url = event.notification.data?.url ?? '/'
event.waitUntil(
clients.matchAll({ type: 'window', includeUncontrolled: true }).then((clientList) => {
const existing = clientList.find((c) => c.url === url && 'focus' in c)
if (existing) return existing.focus()
return clients.openWindow(url)
})
)
})
```
---
## 8. Background Sync
Background sync queues failed requests and retries them when connectivity returns. Chromium only.
### Setup in next.config.js
```js
// In runtimeCaching array:
{
urlPattern: ({ url }) => url.pathname.startsWith('/api/submit'),
handler: 'NetworkOnly',
method: 'POST',
options: {
backgroundSync: {
name: 'submitQueue',
options: {
maxRetentionTime: 24 * 60, // minutes — retry for 24 hours
},
},
},
}
```
### Manual background sync (custom SW)
```js
// In sw-custom.js
import { BackgroundSyncPlugin } from 'workbox-background-sync'
import { registerRoute } from 'workbox-routing'
import { NetworkOnly } from 'workbox-strategies'
const bgSyncPlugin = new BackgroundSyncPlugin('formQueue', {
maxRetentionTime: 24 * 60,
onSync: async ({ queue }) => {
let entry
while ((entry = await queue.shiftRequest())) {
try {
await fetch(entry.request)
} catch {
await queue.unshiftRequest(entry)
throw new Error('Sync failed, retrying later')
}
}
},
})
registerRoute(
({ url }) => url.pathname === '/api/forms/submit',
new NetworkOnly({ plugins: [bgSyncPlugin] }),
'POST'
)
```
### IndexedDB queue for complex offline actions
```ts
// lib/offlineQueue.ts
interface QueuedAction {
id: string
type: string
payload: unknown
createdAt: number
}
const DB_NAME = 'offlineQueue'
const STORE_NAME = 'actions'
async function openDb(): Promise {
return new Promise((resolve, reject) => {
const request = indexedDB.open(DB_NAME, 1)
request.onupgradeneeded = () => {
request.result.createObjectStore(STORE_NAME, { keyPath: 'id' })
}
request.onsuccess = () => resolve(request.result)
request.onerror = () => reject(request.error)
})
}
export async function enqueueAction(type: string, payload: unknown): Promise {
const db = await openDb()
const action: QueuedAction = { id: crypto.randomUUID(), type, payload, createdAt: Date.now() }
return new Promise((resolve, reject) => {
const tx = db.transaction(STORE_NAME, 'readwrite')
tx.objectStore(STORE_NAME).add(action)
tx.oncomplete = () => resolve()
tx.onerror = () => reject(tx.error)
})
}
export async function flushQueue(processor: (action: QueuedAction) => Promise): Promise {
const db = await openDb()
const actions: QueuedAction[] = await new Promise((resolve, reject) => {
const tx = db.transaction(STORE_NAME, 'readonly')
const req = tx.objectStore(STORE_NAME).getAll()
req.onsuccess = () => resolve(req.result)
req.onerror = () => reject(req.error)
})
for (const action of actions) {
await processor(action)
// Remove after successful processing
await new Promise((resolve, reject) => {
const tx = db.transaction(STORE_NAME, 'readwrite')
tx.objectStore(STORE_NAME).delete(action.id)
tx.oncomplete = () => resolve()
tx.onerror = () => reject(tx.error)
})
}
}
```
### Flush on reconnect
```tsx
// In your root layout or _app
useEffect(() => {
const handleOnline = async () => {
await flushQueue(async (action) => {
await fetch('/api/sync', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(action),
})
})
}
window.addEventListener('online', handleOnline)
return () => window.removeEventListener('online', handleOnline)
}, [])
```
---
## 9. App Shortcuts
Shortcuts appear on desktop (right-click app icon in taskbar) and mobile (long-press home screen icon). Already defined in the manifest — here is guidance on making them work well.
### Rules for shortcuts:
- Maximum 4 shortcuts (browsers cap it)
- Each needs a dedicated icon at 96x96 (some browsers also use 192x192)
- URLs must be within the same origin as `start_url`
- Use `?source=shortcut` to track usage in analytics
### Dynamic shortcuts via Service Worker (Chrome 96+)
```js
// In sw-custom.js — update shortcuts based on user state
self.addEventListener('activate', (event) => {
event.waitUntil(
(async () => {
if ('shortcuts' in navigator) {
await navigator.shortcuts.set([
{
name: 'Recent Items',
url: '/recent',
icons: [{ src: '/icons/shortcut-recent.png', sizes: '96x96' }],
},
])
}
})()
)
})
```
### Shortcut icon generation
```bash
# Create 96x96 icons for each shortcut
# scripts/generate-shortcut-icons.mjs
import sharp from 'sharp'
const shortcuts = ['new', 'dashboard', 'settings', 'search']
for (const name of shortcuts) {
await sharp('public/icons/icon-source.png')
.resize(96, 96)
.png()
.toFile(`public/icons/shortcut-${name}.png`)
console.log(`Generated shortcut-${name}.png`)
}
```
---
## 10. Update Flow
When a new service worker is deployed, the old SW keeps running until all tabs are closed. A good UX prompts the user to reload.
### `hooks/useServiceWorkerUpdate.ts`
```tsx
import { useEffect, useState } from 'react'
export function useServiceWorkerUpdate() {
const [updateAvailable, setUpdateAvailable] = useState(false)
const [registration, setRegistration] = useState(null)
useEffect(() => {
if (!('serviceWorker' in navigator)) return
navigator.serviceWorker.getRegistration().then((reg) => {
if (!reg) return
setRegistration(reg)
// SW already waiting (e.g., user had another tab open)
if (reg.waiting) {
setUpdateAvailable(true)
return
}
// New SW installing
reg.addEventListener('updatefound', () => {
const newWorker = reg.installing
if (!newWorker) return
newWorker.addEventListener('statechange', () => {
if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
setUpdateAvailable(true)
}
})
})
})
// Reload all clients once new SW takes control
let refreshing = false
navigator.serviceWorker.addEventListener('controllerchange', () => {
if (refreshing) return
refreshing = true
window.location.reload()
})
}, [])
const applyUpdate = () => {
if (!registration?.waiting) return
registration.waiting.postMessage({ type: 'SKIP_WAITING' })
}
return { updateAvailable, applyUpdate }
}
```
### Update banner
```tsx
// components/UpdateBanner.tsx
'use client'
import { useServiceWorkerUpdate } from '@/hooks/useServiceWorkerUpdate'
export function UpdateBanner() {
const { updateAvailable, applyUpdate } = useServiceWorkerUpdate()
if (!updateAvailable) return null
return (
A new version is available.
)
}
```
### Wire it all together in root layout
```tsx
// app/layout.tsx additions
import { OfflineBanner } from '@/components/OfflineBanner'
import { InstallPrompt } from '@/components/InstallPrompt'
import { UpdateBanner } from '@/components/UpdateBanner'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
---
## 11. Testing
### Chrome DevTools — Application panel
1. Open DevTools → Application tab
2. **Manifest** — check name, icons, theme_color; look for validation errors
3. **Service Workers** — verify SW is registered and active; use "Update on reload" during development; test "Offline" checkbox
4. **Cache Storage** — inspect what's cached per cache name; delete entries to test cache misses
5. **Background Sync** — see queued sync events under "Background Sync"
6. **Push Messaging** — send a test push without a server using "Push" button
7. **Storage** — quota usage and persistent storage status
### Lighthouse PWA audit
```bash
# CLI audit
npx lighthouse https://your-app.com \
--only-categories=pwa \
--output=html \
--output-path=pwa-report.html \
--chrome-flags="--headless"
# Or in DevTools: Lighthouse tab → select PWA category → Analyze
```
**Lighthouse PWA checklist (installable):**
- [ ] Has valid manifest with required fields
- [ ] Has maskable icon
- [ ] Registered service worker
- [ ] Responds with 200 when offline
- [ ] Sets ``
- [ ] HTTPS (or localhost)
### Playwright PWA tests
```ts
// tests/pwa.spec.ts
import { test, expect } from '@playwright/test'
test('offline page shows when network is blocked', async ({ page, context }) => {
await page.goto('/')
// Navigate to a page not in cache
await context.setOffline(true)
await page.goto('/uncached-page', { waitUntil: 'networkidle' })
await expect(page.getByRole('heading', { name: /offline/i })).toBeVisible()
})
test('manifest is valid', async ({ request }) => {
const res = await request.get('/manifest.json')
expect(res.status()).toBe(200)
const manifest = await res.json()
expect(manifest.name).toBeTruthy()
expect(manifest.icons).toHaveLength(expect.any(Number))
expect(manifest.start_url).toBeTruthy()
})
test('service worker registers', async ({ page }) => {
await page.goto('/')
const swRegistered = await page.evaluate(() =>
navigator.serviceWorker.getRegistration().then((reg) => !!reg)
)
expect(swRegistered).toBe(true)
})
```
### Manual install testing
1. Open app in Chrome on Android via USB debug or real URL
2. Should see install banner after enough engagement signals (visiting 2+ times, 30+ seconds)
3. Or: DevTools → Application → Manifest → "Add to homescreen" button
4. Verify shortcut icons, splash screen, and theme_color on launch
---
## 12. Anti-Patterns
### Caching everything blindly
```js
// BAD — caches authenticated API responses for all users
{
urlPattern: /^\/api\/.*/,
handler: 'CacheFirst', // Wrong for auth endpoints
}
// GOOD — network-first for auth, cache-first only for public static
{
urlPattern: /^\/api\/user\/.*/,
handler: 'NetworkOnly', // Never cache user-specific data
}
{
urlPattern: /^\/api\/public\/.*/,
handler: 'StaleWhileRevalidate',
options: { expiration: { maxAgeSeconds: 3600 } },
}
```
### No offline fallback
```js
// BAD — next-pwa config with no fallback
// When the user is offline and visits a page not in cache, they get browser's generic error
// GOOD — always set a fallback document
fallbacks: {
document: '/offline',
}
```
### Ignoring the update flow
```js
// BAD — skipWaiting: true with no user notification
// The page reloads silently while the user is typing — data loss risk
// GOOD — skipWaiting: false + prompt user with UpdateBanner (see Section 10)
skipWaiting: false,
```
### Caching POST requests without background sync
```js
// BAD — caching POST responses means stale mutations
{
urlPattern: /^\/api\/submit/,
handler: 'CacheFirst', // Never cache POST
method: 'POST',
}
// GOOD — use NetworkOnly + BackgroundSyncPlugin for POST
{
urlPattern: /^\/api\/submit/,
handler: 'NetworkOnly',
method: 'POST',
options: { backgroundSync: { name: 'submitQueue' } },
}
```
### Requesting push permission on page load
```tsx
// BAD — browsers will block sites that ask immediately
useEffect(() => {
Notification.requestPermission() // Instant block — user hasn't opted in
}, [])
// GOOD — ask only after explicit user action
```
### Missing maskable icon
```json
// BAD — only 'any' purpose icons
{ "src": "/icon-512.png", "sizes": "512x512", "purpose": "any" }
// GOOD — both any and maskable
{ "src": "/icon-512.png", "sizes": "512x512", "purpose": "any" },
{ "src": "/icon-maskable-512.png", "sizes": "512x512", "purpose": "maskable" }
// Without maskable, Android shows your icon in a white circle/square
```
### Assuming Safari supports everything
```ts
// Check before using Chromium-only APIs
if ('BackgroundSync' in self) {
// Background sync — Chromium only
}
if ('PushManager' in window) {
// Push — supported, but iOS requires app to be installed to home screen
}
if ('periodicSync' in registration) {
// Periodic background sync — Chromium only, requires site engagement score
}
```