Progressive Web Apps 2026: Complete Development Guide

1. PWA Architecture Overview

A PWA is not a framework or library — it's an architectural pattern built on three web platform primitives: service workers, the Web App Manifest, and HTTPS. Everything else (push notifications, background sync, IndexedDB, Web Share API) builds on top of these foundations.

The App Shell architecture is the recommended PWA pattern for single-page applications. Separate your UI shell (navigation, sidebars, layout components) from your content. Cache the shell aggressively so it loads instantly on repeat visits, then fetch content dynamically. This pattern delivers sub-1-second repeat visit load times regardless of network conditions because the UI frame is always available from cache.

2. Service Worker Lifecycle

Understanding the service worker lifecycle is non-negotiable for reliable PWA development. Misunderstanding it causes stale caches, broken updates, and inconsistent offline behavior. The lifecycle has four states: installing, installed (waiting), activating, and activated.

// Install: precache app shell
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open('app-shell-v2').then((cache) =>
      cache.addAll(['/index.html', '/app.css', '/app.js'])
    )
  );
  self.skipWaiting(); // Activate immediately
});

// Activate: clean up old caches
self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(
        keys.filter((k) => k !== 'app-shell-v2').map((k) => caches.delete(k))
      )
    )
  );
  self.clients.claim(); // Control all open pages
});

3. Caching Strategies

No single caching strategy works for all resource types. The right strategy depends on how frequently the content changes, how critical freshness is, and how tolerable staleness is for the user. Apply these strategies by resource type, not globally.

Cache size management is critical but often overlooked. The browser allocates a storage quota per origin (typically 60% of available device storage). Set explicit maximum entry counts and age limits on all runtime caches using Workbox's ExpirationPlugin — otherwise, your cache grows unbounded and browsers start evicting entries unpredictably. A practical limit: 50 entries maximum for API responses, 200 entries for images, 7-day maximum age for all runtime caches.

4. Web Push Notifications

Web Push allows PWAs to send notifications even when the browser is closed — the same capability that drives mobile app re-engagement. Web Push notifications for installed PWAs on Android achieve open rates of 7-15%, compared to 1-4% for email, making them the most effective digital re-engagement channel per send.

5. Web App Manifest

The Web App Manifest is a JSON file that controls how your PWA appears when installed: its name, icon, splash screen, theme color, and whether it launches in a standalone window or a browser tab. Every field matters — missing icons in required sizes or an invalid start_url will silently block installation prompts.

{
  "name": "Your App Name",
  "short_name": "AppName",
  "description": "Your app description for app stores",
  "start_url": "/?source=pwa",
  "display": "standalone",
  "orientation": "portrait-primary",
  "theme_color": "#6d28d9",
  "background_color": "#ffffff",
  "scope": "/",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
    {
      "src": "/icons/icon-512-maskable.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "screenshots": [
    {
      "src": "/screenshots/desktop.png",
      "sizes": "1280x720",
      "type": "image/png",
      "form_factor": "wide"
    }
  ],
  "categories": ["productivity", "utilities"]
}

The purpose: "maskable" icon variant is critical for Android. Maskable icons fill the entire icon shape (circle, squircle, etc.) chosen by the launcher, preventing the white-box appearance that standard icons show in some Android environments. Use the Maskable.app tool to verify your icon looks correct in all standard mask shapes before releasing. Generate all icon sizes (72, 96, 128, 144, 152, 192, 384, 512px) from a single SVG source.

6. Installation Prompts

Chrome triggers the beforeinstallprompt event when a PWA meets all installability criteria. This event is your opportunity to show a custom installation UI rather than relying on the generic browser prompt. Capturing and deferring this event is the key to controlling the installation experience.

let deferredPrompt: BeforeInstallPromptEvent | null = null;

// Capture the event — do NOT show immediately
window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  deferredPrompt = e as BeforeInstallPromptEvent;
  // Show your custom install button/banner here
  showInstallBanner();
});

// Trigger when user clicks your custom install UI
async function handleInstallClick() {
  if (!deferredPrompt) return;
  deferredPrompt.prompt();
  const { outcome } = await deferredPrompt.userChoice;
  // 'accepted' or 'dismissed'
  analytics.track('pwa_install_prompt', { outcome });
  deferredPrompt = null;
}

// Track successful installation
window.addEventListener('appinstalled', () => {
  analytics.track('pwa_installed');
  hideInstallBanner();
});

Time your installation prompt strategically. The highest conversion rates occur after a user has experienced genuine value — after completing a purchase, viewing 3+ pages, or finishing a task. Show the install banner with a clear value proposition: "Install for faster access and offline support" outperforms a generic "Add to Home Screen." A/B test your install prompt messaging — small wording changes regularly produce 20-40% differences in acceptance rates.

7. Offline-First Design

Offline-first is not just a technical pattern — it's a design philosophy that treats network access as an enhancement rather than a requirement. Every UI decision should answer: what does this look like when the user is offline, has a slow connection, or is in a spotty coverage area?

8. Performance & Testing

PWA performance is measurable, auditable, and directly tied to business outcomes. Google's Lighthouse provides automated scoring across Performance, Accessibility, Best Practices, SEO, and a dedicated PWA audit. Target 90+ across all categories — not for vanity, but because these scores correlate with Google Search rankings and user conversion rates.

Test your service worker with the Workbox Chrome DevTools panel, which shows cache contents, simulates offline mode, and traces request routing. Simulate poor network conditions (3G, 4G) in DevTools Network throttling to catch performance regressions that don't appear on fast connections. Test on real low-end Android devices — a Moto G4-class device with CPU throttling enabled reveals UX problems that high-end developer machines hide.

For the performance optimization layer that underpins PWA speed, our web performance optimization guide covers Core Web Vitals in depth. For the React-specific rendering patterns that make PWAs fast on initial load, see our guide on React Server Components in production.

Frequently Asked Questions