Progressive Web Apps 2026: PWA Performance Guide

// Register service worker on page load
if ('serviceWorker' in navigator) {
  window.addEventListener('load', async () => {
    try {
      const registration = await navigator.serviceWorker.register(
        '/service-worker.js',
        { scope: '/' }
      );
      console.log('SW registered:', registration.scope);

      // Check for waiting update
      if (registration.waiting) {
        notifyUserOfUpdate(registration);
      }

      // Listen for future updates
      registration.addEventListener('updatefound', () => {
        const newWorker = registration.installing;
        newWorker?.addEventListener('statechange', () => {
          if (
            newWorker.state === 'installed' &&
            navigator.serviceWorker.controller
          ) {
            notifyUserOfUpdate(registration);
          }
        });
      });
    } catch (error) {
      console.error('SW registration failed:', error);
    }
  });
}

// In your service worker (service-worker.js)
// Activate: clean up old caches
self.addEventListener('activate', (event) => {
  const CURRENT_CACHE = 'app-shell-v3';
  event.waitUntil(
    caches.keys().then((cacheNames) =>
      Promise.all(
        cacheNames
          .filter((name) => name !== CURRENT_CACHE)
          .map((name) => caches.delete(name))
      )
    )
  );
  // Take control of all open clients immediately
  self.clients.claim();
});

// Listen for skip-waiting message from the app
self.addEventListener('message', (event) => {
  if (event.data?.type === 'SKIP_WAITING') {
    self.skipWaiting();
  }
});

// Precache app shell assets during install
import { precacheAndRoute } from 'workbox-precaching';

// Workbox injects the manifest during build
// __WB_MANIFEST is replaced with the actual asset list
precacheAndRoute(self.__WB_MANIFEST);

// This precaches:
// - /index.html
// - /static/js/main.[hash].js
// - /static/css/main.[hash].css
// - /static/media/logo.[hash].svg
// All with content-hash-based cache busting

// Register a sync event from the app
async function submitFormOffline(formData) {
  const registration = await navigator.serviceWorker.ready;

  // Store the data in IndexedDB for the sync
  await db.pendingSubmissions.add({ formData, timestamp: Date.now() });

  // Register a background sync
  await registration.sync.register('submit-form');
  // The browser will call the sync event when online
}

// In the service worker: handle the sync
self.addEventListener('sync', (event) => {
  if (event.tag === 'submit-form') {
    event.waitUntil(
      db.pendingSubmissions.toArray().then((pending) =>
        Promise.all(
          pending.map((item) =>
            fetch('/api/submit', {
              method: 'POST',
              body: JSON.stringify(item.formData),
            }).then(() => db.pendingSubmissions.delete(item.id))
          )
        )
      )
    );
  }
});

// public/manifest.json — Complete PWA manifest
{
  "name": "My Progressive Web App",
  "short_name": "MyPWA",
  "description": "An offline-capable, installable web application",
  "start_url": "/?source=pwa",
  "display": "standalone",
  "orientation": "portrait-primary",
  "background_color": "#ffffff",
  "theme_color": "#2563eb",
  "lang": "en",
  "scope": "/",
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable any"
    }
  ],
  "shortcuts": [
    {
      "name": "New Task",
      "url": "/tasks/new",
      "icons": [{ "src": "/icons/new-task.png", "sizes": "192x192" }]
    }
  ],
  "screenshots": [
    {
      "src": "/screenshots/desktop.png",
      "sizes": "1280x720",
      "type": "image/png",
      "form_factor": "wide"
    }
  ]
}

// Lighthouse CI config for PWA performance gates
// lighthouserc.json
{
  "ci": {
    "assert": {
      "assertions": {
        "categories:pwa": ["error", { "minScore": 0.9 }],
        "categories:performance": ["error", { "minScore": 0.9 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "interactive": ["error", { "maxNumericValue": 3500 }],
        "total-byte-weight": ["warn", { "maxNumericValue": 1500000 }],
        "uses-optimized-images": ["warn", {}],
        "service-worker": ["error", {}],
        "installable-manifest": ["error", {}]
      }
    }
  }
}

// components/service-worker-register.tsx
'use client';

import { useEffect } from 'react';

export function ServiceWorkerRegister() {
  useEffect(() => {
    if ('serviceWorker' in navigator) {
      navigator.serviceWorker
        .register('/sw.js')
        .then((reg) => {
          console.log('SW registered, scope:', reg.scope);

          reg.addEventListener('updatefound', () => {
            const newSW = reg.installing;
            newSW?.addEventListener('statechange', () => {
              if (newSW.state === 'installed' && navigator.serviceWorker.controller) {
                // Notify user of available update
                dispatchEvent(new CustomEvent('sw-update-available', { detail: reg }));
              }
            });
          });
        })
        .catch((err) => console.error('SW registration failed:', err));
    }
  }, []);

  return null; // No UI — registration only
}

// app/layout.tsx — Add to root layout
import { ServiceWorkerRegister } from '@/components/service-worker-register';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <link rel="manifest" href="/manifest.json" />
        <meta name="theme-color" content="#2563eb" />
      </head>
      <body>
        <ServiceWorkerRegister />
        {children}
      </body>
    </html>
  );
}

// next.config.ts — next-pwa configuration
import withPWA from '@ducanh2912/next-pwa';

const withPWAConfig = withPWA({
  dest: 'public',
  disable: process.env.NODE_ENV === 'development',
  register: true,
  skipWaiting: false, // Handle updates manually
  runtimeCaching: [
    {
      // Cache API responses with NetworkFirst
      urlPattern: /^https://api.yoursite.com/.*/,
      handler: 'NetworkFirst',
      options: {
        cacheName: 'api-cache',
        expiration: { maxEntries: 200, maxAgeSeconds: 5 * 60 },
        networkTimeoutSeconds: 10,
      },
    },
    {
      // Cache images with CacheFirst
      urlPattern: /.(?:png|jpg|jpeg|svg|gif|webp|avif)$/,
      handler: 'CacheFirst',
      options: {
        cacheName: 'image-cache',
        expiration: { maxEntries: 100, maxAgeSeconds: 30 * 24 * 60 * 60 },
      },
    },
  ],
});

export default withPWAConfig({
  // Your Next.js config here
});

// Track cache hits in your service worker
self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((cached) => {
      if (cached) {
        // Report cache hit to analytics
        self.clients.matchAll().then((clients) => {
          clients.forEach((client) =>
            client.postMessage({
              type: 'CACHE_HIT',
              url: event.request.url,
            })
          );
        });
        return cached;
      }

      // Cache miss — fetch from network
      return fetch(event.request);
    })
  );
});

// In your app, listen for cache hit messages
navigator.serviceWorker.addEventListener('message', (event) => {
  if (event.data?.type === 'CACHE_HIT') {
    analytics.track('sw_cache_hit', { url: event.data.url });
  }
});