Progressive Web App (PWA)

What is it?

A set of web capabilities that make your app installable, offline-capable, and native-like. Not a library—a pattern using manifest.json, service workers, and HTTPS.

What is it for?

• Mobile-first apps needing native-like experience
• Offline-required apps (field workers, travel, poor connectivity)
• Cross-platform reach without app store overhead
• Fast deployment without app store approval delays

Decision framework:

Why was it chosen?

v10r's verdict (2026 task force — see blueprint/pwa.md): pure PWA, Capacitor rejected for this stack — the static-bundle variant forces an SSR→SPA rewrite (kills cookies, CSRF, form actions, passkey rpID, Google OAuth via the webview ban) and the remote-URL variant is maintainer-discouraged with documented SW-update wedges. If Play Store presence is ever wanted, TWA wraps the existing PWA unchanged (but carries a ~annual target-SDK re-bump obligation). On iOS the installed PWA is the app.

SvelteKit Implementation Options

@vite-pwa/sveltekit:

• Latest: v1.1.0 (Nov 2025); maintained but low-velocity
• Zero-config value evaporates for SSR apps (generateSW precaches a build glob; SSR routes aren't in it → you end up in injectManifest writing a custom SW anyway)
• Known unfixed issue: infinite reload loop on SvelteKit error pages (#65)

SvelteKit built-in — what v10r uses (src/service-worker.ts, policy in $lib/pwa/sw-policy.ts):

• $service-worker module provides build, files, prerendered, version
• Readable, zero-dep, unit-testable caching policy — the SW file is itself the showcase
• Accepted cost: version is app-global, so every deploy invalidates the whole precache (no per-file revisioning exists for SSR); the re-download is background

Installability no longer requires a service worker at all: Chrome dropped the SW requirement (Lighthouse 11 removed the PWA category) — a valid manifest alone is installable. iOS 26's share sheet defaults the "Open as Web App" toggle to on.

Caching Strategies

Rule of thumb:

• Static assets (hashed) → Cache First
• HTML pages → Network First with cache fallback
• API responses → Depends on freshness requirements

Manifest Requirements

Minimum for installability (Chromium):

{
  "name": "App Name",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

Push Notifications

iOS push caveats:

• No automatic install prompt (manual "Add to Home Screen")
• Permission must be user-triggered (button click)
• No background sync (notifications only when app open)

Declarative Web Push (Safari/iOS 18.4+, March 2025; absorbed into the W3C Push API Working Draft Dec 2025): a standardized JSON payload the OS renders with no service worker code — the SW becomes an optional transformer, and browsers that don't understand the format (Chrome/Android today) deliver the same payload as a classic push event. v10r sends the declarative JSON as its single payload shape (see blueprint/pwa.md); field evidence is still thin, so verify on-device rather than assuming interop.

Known limitations

iOS Safari (Critical)

EU/DMA note: Apple's Feb 2024 removal of Home Screen web apps in the EU was reversed in March 2024; PWA support has held since (claims that EU PWAs still lack standalone/push are stale SEO content).

iOS workarounds:

• Guide users through install with visual prompts
• Keep cache small, prioritize critical assets
• Use localStorage for critical user data
• Implement OAuth with same-domain redirect

Browser Support Matrix

Common Pitfalls

1. Caching /admin routes → Security vulnerability
2. Over-caching APIs → Stale data in critical flows
3. No cache versioning → Users stuck with old data
4. Forgetting offline fallback → Broken experience when offline
5. Testing only in Chrome → Works there, breaks on iOS

Performance Considerations

Best practices:

• Don't cache videos (too large, triggers eviction)
• Version caches for clean updates
• Use skipWaiting() with user prompt, not automatically
• Monitor: FCP, TTFB, cache hit rate

Project Fugu APIs (Chromium-only)

New capabilities closing native gap—but limited browser support:

Rule: Use progressive enhancement. Detect support, provide fallbacks.

Related

• notifications - Push notification providers (Novu, FCM)
• ../ops/caching.md - Caching strategy
• ../core/sveltekit.md - Service worker support
• ../vendors.md - Hosting providers