Progressive Web Apps (PWA) Best Practices for 2026

// Register service worker with proper error handling
if ('serviceWorker' in navigator) {
  window.addEventListener('load', async () => {
    try {
      const registration = await navigator.serviceWorker.register('/sw.js', {
        scope: '/'
      });
      
      console.log('ServiceWorker registered:', registration.scope);
      
      // Handle updates
      registration.addEventListener('updatefound', () => {
        const newWorker = registration.installing;
        newWorker.addEventListener('statechange', () => {
          if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
            // New service worker available, prompt user to refresh
            showUpdateNotification();
          }
        });
      });
    } catch (error) {
      console.error('ServiceWorker registration failed:', error);
    }
  });
}

// sw.js - Advanced caching strategies
const CACHE_VERSION = 'v1.0.0';
const STATIC_CACHE = `static-${CACHE_VERSION}`;
const DYNAMIC_CACHE = `dynamic-${CACHE_VERSION}`;
const IMAGE_CACHE = `images-${CACHE_VERSION}`;

const STATIC_ASSETS = [
  '/',
  '/index.html',
  '/styles/main.css',
  '/scripts/app.js',
  '/manifest.json',
  '/offline.html'
];

// Install event - cache static assets
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(STATIC_CACHE)
      .then(cache => cache.addAll(STATIC_ASSETS))
      .then(() => self.skipWaiting())
  );
});

// Fetch event - implement cache strategies
self.addEventListener('fetch', event => {
  const { request } = event;
  const url = new URL(request.url);
  
  // Handle different resource types
  if (request.destination === 'image') {
    event.respondWith(cacheFirstStrategy(request, IMAGE_CACHE));
  } else if (url.pathname.startsWith('/api/')) {
    event.respondWith(networkFirstStrategy(request, DYNAMIC_CACHE));
  } else {
    event.respondWith(staleWhileRevalidate(request, STATIC_CACHE));
  }
});

// Cache-first strategy for images
async function cacheFirstStrategy(request, cacheName) {
  const cachedResponse = await caches.match(request);
  if (cachedResponse) return cachedResponse;
  
  try {
    const networkResponse = await fetch(request);
    const cache = await caches.open(cacheName);
    cache.put(request, networkResponse.clone());
    return networkResponse;
  } catch (error) {
    return caches.match('/images/placeholder.png');
  }
}

// Network-first strategy for API calls
async function networkFirstStrategy(request, cacheName) {
  try {
    const networkResponse = await fetch(request);
    const cache = await caches.open(cacheName);
    cache.put(request, networkResponse.clone());
    return networkResponse;
  } catch (error) {
    const cachedResponse = await caches.match(request);
    return cachedResponse || new Response('Offline', { status: 503 });
  }
}

// Stale-while-revalidate for static assets
async function staleWhileRevalidate(request, cacheName) {
  const cachedResponse = await caches.match(request);
  
  const fetchPromise = fetch(request).then(networkResponse => {
    caches.open(cacheName).then(cache => {
      cache.put(request, networkResponse.clone());
    });
    return networkResponse;
  });
  
  return cachedResponse || fetchPromise;
}

// App shell implementation with lazy loading
class PWAShell {
  constructor() {
    this.shell = document.querySelector('#app-shell');
    this.content = document.querySelector('#app-content');
    this.initializeShell();
  }
  
  async initializeShell() {
    // Load critical CSS inline
    this.injectCriticalCSS();
    
    // Render shell immediately
    this.renderShell();
    
    // Load content asynchronously
    await this.loadDynamicContent();
  }
  
  injectCriticalCSS() {
    const criticalCSS = `
      /* Critical styles for app shell */
      .app-shell { display: flex; flex-direction: column; height: 100vh; }
      .header { position: fixed; top: 0; width: 100%; z-index: 1000; }
      .content { flex: 1; overflow-y: auto; margin-top: 60px; }
    `;
    
    const style = document.createElement('style');
    style.textContent = criticalCSS;
    document.head.appendChild(style);
  }
  
  renderShell() {
    this.shell.innerHTML = `
      <header class="header">
        <nav>Navigation</nav>
      </header>
      <main class="content">
        <div class="loading-skeleton"></div>
      </main>
    `;
  }
  
  async loadDynamicContent() {
    try {
      const response = await fetch('/api/content');
      const data = await response.json();
      this.content.innerHTML = this.renderContent(data);
    } catch (error) {
      this.renderOfflineContent();
    }
  }
  
  renderContent(data) {
    return data.map(item => `
      <article>
        <h2>${item.title}</h2>
        <p>${item.description}</p>
      </article>
    `).join('');
  }
  
  renderOfflineContent() {
    this.content.innerHTML = `
      <div class="offline-message">
        <h2>You're offline</h2>
        <p>Content will load when you're back online</p>
      </div>
    `;
  }
}

// Initialize app shell
new PWAShell();

// Webpack configuration for optimal code splitting
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          priority: 10
        },
        common: {
          minChunks: 2,
          priority: 5,
          reuseExistingChunk: true
        }
      }
    },
    runtimeChunk: 'single',
    minimize: true
  },
  performance: {
    maxAssetSize: 244000,
    maxEntrypointSize: 244000,
    hints: 'warning'
  }
};

{
  "name": "My Progressive Web App",
  "short_name": "MyPWA",
  "description": "A comprehensive PWA following 2026 best practices",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait-primary",
  "theme_color": "#4285f4",
  "background_color": "#ffffff",
  "icons": [
    {
      "src": "/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ],
  "categories": ["productivity", "utilities"],
  "screenshots": [
    {
      "src": "/screenshots/desktop-1.png",
      "sizes": "1280x720",
      "type": "image/png",
      "form_factor": "wide"
    },
    {
      "src": "/screenshots/mobile-1.png",
      "sizes": "750x1334",
      "type": "image/png",
      "form_factor": "narrow"
    }
  ],
  "shortcuts": [
    {
      "name": "Create New",
      "short_name": "New",
      "description": "Create a new item",
      "url": "/create",
      "icons": [
        {
          "src": "/icons/create-96x96.png",
          "sizes": "96x96"
        }
      ]
    }
  ],
  "related_applications": [],
  "prefer_related_applications": false
}

// Custom install prompt implementation
class PWAInstaller {
  constructor() {
    this.deferredPrompt = null;
    this.installButton = document.querySelector('#install-button');
    this.setupInstallPrompt();
  }
  
  setupInstallPrompt() {
    // Listen for beforeinstallprompt event
    window.addEventListener('beforeinstallprompt', (e) => {
      // Prevent default prompt
      e.preventDefault();
      
      // Store the event for later use
      this.deferredPrompt = e;
      
      // Show custom install UI
      this.showInstallPromotion();
    });
    
    // Handle install button click
    this.installButton?.addEventListener('click', () => {
      this.promptInstall();
    });
    
    // Track installation
    window.addEventListener('appinstalled', () => {
      this.trackInstallation();
      this.deferredPrompt = null;
    });
  }
  
  showInstallPromotion() {
    // Check if user has dismissed before
    const dismissed = localStorage.getItem('install-dismissed');
    const installCount = localStorage.getItem('install-prompt-count') || 0;
    
    if (!dismissed && installCount < 3) {
      this.installButton.style.display = 'block';
      localStorage.setItem('install-prompt-count', parseInt(installCount) + 1);
    }
  }
  
  async promptInstall() {
    if (!this.deferredPrompt) return;
    
    // Show the install prompt
    this.deferredPrompt.prompt();
    
    // Wait for user response
    const { outcome } = await this.deferredPrompt.userChoice;
    
    if (outcome === 'dismissed') {
      localStorage.setItem('install-dismissed', 'true');
    }
    
    // Clear the deferred prompt
    this.deferredPrompt = null;
    this.installButton.style.display = 'none';
  }
  
  trackInstallation() {
    // Track successful installation
    if (typeof gtag !== 'undefined') {
      gtag('event', 'pwa_install', {
        event_category: 'engagement',
        event_label: 'PWA Installation'
      });
    }
    
    // Remove install UI elements
    this.installButton.style.display = 'none';
  }
}

// Initialize installer
new PWAInstaller();

// Push notification manager
class PushNotificationManager {
  constructor() {
    this.vapidPublicKey = 'YOUR_VAPID_PUBLIC_KEY';
  }
  
  async requestPermission() {
    // Check if notifications are supported
    if (!('Notification' in window)) {
      console.warn('Notifications not supported');
      return false;
    }
    
    // Request permission at appropriate time
    const permission = await Notification.requestPermission();
    
    if (permission === 'granted') {
      await this.subscribeToPush();
      return true;
    }
    
    return false;
  }
  
  async subscribeToPush() {
    try {
      const registration = await navigator.serviceWorker.ready;
      
      // Subscribe to push notifications
      const subscription = await registration.pushManager.subscribe({
        userVisibleOnly: true,
        applicationServerKey: this.urlBase64ToUint8Array(this.vapidPublicKey)
      });
      
      // Send subscription to server
      await this.sendSubscriptionToServer(subscription);
      
      console.log('Push subscription successful');
    } catch (error) {
      console.error('Push subscription failed:', error);
    }
  }
  
  async sendSubscriptionToServer(subscription) {
    const response = await fetch('/api/push/subscribe', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(subscription)
    });
    
    if (!response.ok) {
      throw new Error('Failed to send subscription to server');
    }
  }
  
  urlBase64ToUint8Array(base64String) {
    const padding = '='.repeat((4 - base64String.length % 4) % 4);
    const base64 = (base64String + padding)
      .replace(/\-/g, '+')
      .replace(/_/g, '/');
    
    const rawData = window.atob(base64);
    const outputArray = new Uint8Array(rawData.length);
    
    for (let i = 0; i < rawData.length; ++i) {
      outputArray[i] = rawData.charCodeAt(i);
    }
    
    return outputArray;
  }
}

// Service worker push event handler
self.addEventListener('push', event => {
  const data = event.data?.json() ?? {};
  
  const options = {
    body: data.body || 'New notification',
    icon: '/icons/icon-192x192.png',
    badge: '/icons/badge-72x72.png',
    vibrate: [200, 100, 200],
    data: {
      url: data.url || '/'
    },
    actions: [
      {
        action: 'open',
        title: 'Open App'
      },
      {
        action: 'close',
        title: 'Close'
      }
    ]
  };
  
  event.waitUntil(
    self.registration.showNotification(data.title || 'Notification', options)
  );
});

// Handle notification clicks
self.addEventListener('notificationclick', event => {
  event.notification.close();
  
  if (event.action === 'open') {
    event.waitUntil(
      clients.openWindow(event.notification.data.url)
    );
  }
});

// Background sync implementation
class BackgroundSyncManager {
  async registerSync(tag, data) {
    try {
      const registration = await navigator.serviceWorker.ready;
      
      // Store data for sync
      await this.storeDataForSync(tag, data);
      
      // Register background sync
      await registration.sync.register(tag);
      
      console.log(`Background sync registered: ${tag}`);
    } catch (error) {
      console.error('Background sync registration failed:', error);
      // Fallback to immediate sync
      await this.immediateSync(tag, data);
    }
  }
  
  async storeDataForSync(tag, data) {
    const db = await this.openDatabase();
    const tx = db.transaction('sync-queue', 'readwrite');
    const store = tx.objectStore('sync-queue');
    
    await store.put({
      tag,
      data,
      timestamp: Date.now()
    });
  }
  
  async openDatabase() {
    return new Promise((resolve, reject) => {
      const request = indexedDB.open('pwa-sync-db', 1);
      
      request.onerror = () => reject(request.error);
      request.onsuccess = () => resolve(request.result);
      
      request.onupgradeneeded = (event) => {
        const db = event.target.result;
        if (!db.objectStoreNames.contains('sync-queue')) {
          db.createObjectStore('sync-queue', { keyPath: 'tag' });
        }
      };
    });
  }
  
  async immediateSync(tag, data) {
    // Attempt immediate sync as fallback
    try {
      await this.syncData(tag, data);
    } catch (error) {
      console.error('Immediate sync failed:', error);
    }
  }
  
  async syncData(tag, data) {
    const response = await fetch('/api/sync', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ tag, data })
    });
    
    if (!response.ok) {
      throw new Error('Sync failed');
    }
  }
}

// Service worker sync event handler
self.addEventListener('sync', event => {
  if (event.tag.startsWith('sync-')) {
    event.waitUntil(handleSync(event.tag));
  }
});

async function handleSync(tag) {
  const db = await openDatabase();
  const tx = db.transaction('sync-queue', 'readonly');
  const store = tx.objectStore('sync-queue');
  const syncData = await store.get(tag);
  
  if (syncData) {
    try {
      await fetch('/api/sync', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(syncData.data)
      });
      
      // Remove from queue after successful sync
      const deleteTx = db.transaction('sync-queue', 'readwrite');
      await deleteTx.objectStore('sync-queue').delete(tag);
    } catch (error) {
      console.error('Sync failed:', error);
      throw error; // Retry later
    }
  }
}

// Security headers configuration (Node.js/Express example)
const helmet = require('helmet');

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      imgSrc: ["'self'", 'data:', 'https:'],
      connectSrc: ["'self'", 'https://api.example.com'],
      fontSrc: ["'self'"],
      objectSrc: ["'none'"],
      mediaSrc: ["'self'"],
      frameSrc: ["'none'"]
    }
  },
  hsts: {
    maxAge: 31536000,
    includeSubDomains: true,
    preload: true
  },
  referrerPolicy: {
    policy: 'strict-origin-when-cross-origin'
  }
}));

// Privacy-conscious data management
class PrivacyManager {
  constructor() {
    this.consentKey = 'user-consent';
    this.preferencesKey = 'privacy-preferences';
  }
  
  hasConsent(feature) {
    const consent = this.getConsent();
    return consent?.[feature] === true;
  }
  
  getConsent() {
    const stored = localStorage.getItem(this.consentKey);
    return stored ? JSON.parse(stored) : null;
  }
  
  async requestConsent() {
    return new Promise((resolve) => {
      const modal = this.createConsentModal();
      document.body.appendChild(modal);
      
      modal.addEventListener('consent-given', (e) => {
        this.saveConsent(e.detail);
        modal.remove();
        resolve(e.detail);
      });
    });
  }
  
  saveConsent(preferences) {
    localStorage.setItem(this.consentKey, JSON.stringify(preferences));
    localStorage.setItem('consent-timestamp', Date.now().toString());
  }
  
  createConsentModal() {
    const modal = document.createElement('div');
    modal.className = 'privacy-consent-modal';
    modal.innerHTML = `
      <div class="consent-content">
        <h3>Privacy Settings</h3>
        <label>
          <input type="checkbox" name="analytics" />
          Allow analytics to improve experience
        </label>
        <label>
          <input type="checkbox" name="notifications" />
          Enable push notifications
        </label>
        <button id="save-consent">Save Preferences</button>
      </div>
    `;
    
    modal.querySelector('#save-consent').addEventListener('click', () => {
      const preferences = {
        analytics: modal.querySelector('[name="analytics"]').checked,
        notifications: modal.querySelector('[name="notifications"]').checked
      };
      
      modal.dispatchEvent(new CustomEvent('consent-given', { 
        detail: preferences 
      }));
    });
    
    return modal;
  }
  
  clearData() {
    // Provide users with data deletion capability
    localStorage.clear();
    indexedDB.databases().then(dbs => {
      dbs.forEach(db => indexedDB.deleteDatabase(db.name));
    });
    
    caches.keys().then(names => {
      names.forEach(name => caches.delete(name));
    });
  }
}

const privacyManager = new PrivacyManager();

// Core Web Vitals monitoring
class WebVitalsMonitor {
  constructor() {
    this.metrics = {
      LCP: null,  // Largest Contentful Paint
      FID: null,  // First Input Delay
      CLS: null   // Cumulative Layout Shift
    };
    this.initializeMonitoring();
  }
  
  initializeMonitoring() {
    // Monitor LCP
    new PerformanceObserver((entryList) => {
      const entries = entryList.getEntries();
      const lastEntry = entries[entries.length - 1];
      this.metrics.LCP = lastEntry.renderTime || lastEntry.loadTime;
      this.reportMetric('LCP', this.metrics.LCP);
    }).observe({ entryTypes: ['largest-contentful-paint'] });
    
    // Monitor FID
    new PerformanceObserver((entryList) => {
      const firstInput = entryList.getEntries()[0];
      this.metrics.FID = firstInput.processingStart - firstInput.startTime;
      this.reportMetric('FID', this.metrics.FID);
    }).observe({ entryTypes: ['first-input'] });
    
    // Monitor CLS
    let clsValue = 0;
    new PerformanceObserver((entryList) => {
      for (const entry of entryList.getEntries()) {
        if (!entry.hadRecentInput) {
          clsValue += entry.value;
          this.metrics.CLS = clsValue;
        }
      }
      this.reportMetric('CLS', this.metrics.CLS);
    }).observe({ entryTypes: ['layout-shift'] });
  }
  
  reportMetric(name, value) {
    // Report to analytics
    if (typeof gtag !== 'undefined') {
      gtag('event', 'web_vitals', {
        event_category: 'Performance',
        event_label: name,
        value: Math.round(value),
        non_interaction: true
      });
    }
    
    // Send to custom analytics endpoint
    this.sendToAnalytics(name, value);
  }
  
  async sendToAnalytics(metric, value) {
    try {
      await fetch('/api/analytics/vitals', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          metric,
          value,
          timestamp: Date.now(),
          url: window.location.href
        }),
        keepalive: true
      });
    } catch (error) {
      console.error('Analytics reporting failed:', error);
    }
  }
}

// Initialize monitoring
const vitalsMonitor = new WebVitalsMonitor();

# .github/workflows/pwa-audit.yml
name: PWA Quality Audit

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build application
        run: npm run build
      
      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
      
      - name: Upload results
        uses: actions/upload-artifact@v3
        with:
          name: lighthouse-results
          path: .lighthouseci

// lighthouserc.js configuration
module.exports = {
  ci: {
    collect: {
      startServerCommand: 'npm run serve',
      url: ['http://localhost:3000'],
      numberOfRuns: 3
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:pwa': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['error', { minScore: 0.9 }],
        'categories:best-practices': ['error', { minScore: 0.9 }],
        'categories:seo': ['error', { minScore: 0.9 }],
        'service-worker': 'error',
        'installable-manifest': 'error',
        'splash-screen': 'error',
        'themed-omnibox': 'error',
        'viewport': 'error',
        'without-javascript': 'off'
      }
    },
    upload: {
      target: 'temporary-public-storage'
    }
  }
};

// Edge deployment configuration (Cloudflare Workers example)
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    
    // Cache strategy for static assets
    if (url.pathname.startsWith('/static/')) {
      return handleStaticAsset(request, ctx);
    }
    
    // Handle API requests
    if (url.pathname.startsWith('/api/')) {
      return handleAPIRequest(request, env);
    }
    
    // Serve app shell for all other routes
    return handleAppShell(request, ctx);
  }
};

async function handleStaticAsset(request, ctx) {
  const cache = caches.default;
  let response = await cache.match(request);
  
  if (!response) {
    response = await fetch(request);
    
    // Cache for 1 year
    const headers = new Headers(response.headers);
    headers.set('Cache-Control', 'public, max-age=31536000, immutable');
    
    response = new Response(response.body, {
      status: response.status,
      statusText: response.statusText,
      headers
    });
    
    ctx.waitUntil(cache.put(request, response.clone()));
  }
  
  return response;
}

async function handleAppShell(request, ctx) {
  const cache = caches.default;
  const cacheKey = new Request(new URL('/', request.url));
  
  let response = await cache.match(cacheKey);
  
  if (!response) {
    response = await fetch(request);
    ctx.waitUntil(cache.put(cacheKey, response.clone()));
  }
  
  return response;
}