Progressive Web App (PWA)

When to Use

Making a web app installable on desktop and mobile devices
Adding offline support and resilience to network failures
Configuring a service worker for caching and background tasks
Implementing caching strategies (cache-first, network-first, stale-while-revalidate)
Setting up a web app manifest with icons, theme, and display mode
Adding push notifications or background sync
Implementing an app shell architecture for instant loading
Customizing the install prompt experience
Auditing and improving Lighthouse PWA score
Converting an existing SPA (React, Angular) to a PWA

Official Documentation

web.dev PWA Guide
MDN Progressive Web Apps
Workbox Documentation
Web App Manifest Spec
Service Worker API (MDN)
Push API (MDN)
Background Sync API
Vite PWA Plugin
Lighthouse PWA Audits

Procedure

Add web app manifest to the project
Implement the service worker with appropriate registration
Choose and apply caching strategies for assets and API calls
Implement offline support with fallback pages and queued actions
Review sample PWA setup for a complete React + Vite example
Add install prompt handling (see Install Prompt below)
Test with Lighthouse PWA audit — target 100 score
Validate on multiple devices (mobile, tablet, desktop)

Core Architecture

┌────────────────────────────────────────────┐
│                  Browser                    │
│  ┌──────────────────────────────────────┐  │
│  │            App Shell                  │  │
│  │  (HTML + CSS + JS — cached locally)   │  │
│  └──────────────┬───────────────────────┘  │
│                 │                           │
│  ┌──────────────▼───────────────────────┐  │
│  │         Service Worker                │  │
│  │  ┌───────────┐  ┌─────────────────┐  │  │
│  │  │ Precache  │  │ Runtime Cache   │  │  │
│  │  │ (static)  │  │ (API + dynamic) │  │  │
│  │  └───────────┘  └─────────────────┘  │  │
│  └──────────────┬───────────────────────┘  │
│                 │                           │
└─────────────────┼──────────────────────────┘
                  │
          ┌───────▼───────┐
          │    Network     │
          │  (origin API)  │
          └───────────────┘

Quick Reference — PWA Checklist

| Requirement | How to Meet | |-------------|-------------| | HTTPS | Serve over HTTPS (required for service workers) | | Web App Manifest | manifest.json linked in <head> with name, icons, display | | Service Worker | Register SW that controls fetch events | | Installable | Valid manifest + registered SW + HTTPS | | Offline Fallback | SW returns cached page when network unavailable | | Icons | At least 192×192 and 512×512 PNG icons | | Splash Screen | theme_color + background_color + icon in manifest | | Viewport Meta | <meta name="viewport" content="width=device-width, initial-scale=1"> | | Start URL | start_url in manifest resolves when offline | | Status Bar | theme_color in manifest and <meta name="theme-color"> |

Install Prompt

Handle the beforeinstallprompt event to show a custom install UI:

// hooks/useInstallPrompt.ts
import { useState, useEffect, useCallback } from 'react';

interface BeforeInstallPromptEvent extends Event {
  prompt(): Promise<void>;
  userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>;
}

export function useInstallPrompt() {
  const [installPrompt, setInstallPrompt] =
    useState<BeforeInstallPromptEvent | null>(null);
  const [isInstalled, setIsInstalled] = useState(false);

  useEffect(() => {
    const handler = (e: Event) => {
      e.preventDefault();
      setInstallPrompt(e as BeforeInstallPromptEvent);
    };

    const installedHandler = () => setIsInstalled(true);

    window.addEventListener('beforeinstallprompt', handler);
    window.addEventListener('appinstalled', installedHandler);

    // Check if already installed
    if (window.matchMedia('(display-mode: standalone)').matches) {
      setIsInstalled(true);
    }

    return () => {
      window.removeEventListener('beforeinstallprompt', handler);
      window.removeEventListener('appinstalled', installedHandler);
    };
  }, []);

  const promptInstall = useCallback(async () => {
    if (!installPrompt) return false;
    await installPrompt.prompt();
    const { outcome } = await installPrompt.userChoice;
    setInstallPrompt(null);
    return outcome === 'accepted';
  }, [installPrompt]);

  return { canInstall: !!installPrompt, isInstalled, promptInstall };
}

Push Notifications

// utils/pushNotifications.ts
export async function subscribeToPush(
  vapidPublicKey: string
): Promise<PushSubscription | null> {
  if (!('PushManager' in window)) return null;

  const registration = await navigator.serviceWorker.ready;
  const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: urlBase64ToUint8Array(vapidPublicKey),
  });

  return subscription;
}

function urlBase64ToUint8Array(base64String: string): Uint8Array {
  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
  const base64 = (base64String + padding)
    .replace(/-/g, '+')
    .replace(/_/g, '/');
  const rawData = atob(base64);
  return Uint8Array.from(rawData, (char) => char.charCodeAt(0));
}

Framework Integration

React + Vite (vite-plugin-pwa)

npm install -D vite-plugin-pwa

// vite.config.ts
import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'autoUpdate',
      includeAssets: ['favicon.ico', 'robots.txt', 'apple-touch-icon.png'],
      manifest: {
        name: 'My App',
        short_name: 'App',
        description: 'My Progressive Web App',
        theme_color: '#ffffff',
        background_color: '#ffffff',
        display: 'standalone',
        scope: '/',
        start_url: '/',
        icons: [
          { src: 'pwa-192x192.png', sizes: '192x192', type: 'image/png' },
          { src: 'pwa-512x512.png', sizes: '512x512', type: 'image/png' },
          {
            src: 'pwa-512x512.png',
            sizes: '512x512',
            type: 'image/png',
            purpose: 'any maskable',
          },
        ],
      },
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
        runtimeCaching: [
          {
            urlPattern: /^https:\/\/api\./i,
            handler: 'NetworkFirst',
            options: {
              cacheName: 'api-cache',
              expiration: { maxEntries: 100, maxAgeSeconds: 60 * 60 },
              networkTimeoutSeconds: 10,
            },
          },
        ],
      },
    }),
  ],
});

Angular (@angular/service-worker)

ng add @angular/pwa

This generates ngsw-config.json, manifest.webmanifest, and registers the SW in app.module.ts. Customize caching groups in ngsw-config.json.

Completion Checklist

[ ] manifest.json present with name, short_name, icons, display, start_url, theme_color
[ ] Service worker registered and controlling the page
[ ] Static assets precached (HTML, CSS, JS, fonts, icons)
[ ] API responses cached with appropriate strategy
[ ] Offline fallback page served when network is unavailable
[ ] Install prompt handled with custom UI
[ ] Icons provided: 192×192 and 512×512 (plus maskable variant)
[ ] <meta name="theme-color"> set in HTML <head>
[ ] <meta name="viewport"> set for responsive layout
[ ] HTTPS configured (required for service workers)
[ ] Lighthouse PWA audit score = 100
[ ] Tested on mobile (iOS Safari, Android Chrome) and desktop

Progressive Web App (PWA)

When to Use

Making a web app installable on desktop and mobile devices
Adding offline support and resilience to network failures
Configuring a service worker for caching and background tasks
Implementing caching strategies (cache-first, network-first, stale-while-revalidate)
Setting up a web app manifest with icons, theme, and display mode
Adding push notifications or background sync
Implementing an app shell architecture for instant loading
Customizing the install prompt experience
Auditing and improving Lighthouse PWA score
Converting an existing SPA (React, Angular) to a PWA

Official Documentation

web.dev PWA Guide
MDN Progressive Web Apps
Workbox Documentation
Web App Manifest Spec
Service Worker API (MDN)
Push API (MDN)
Background Sync API
Vite PWA Plugin
Lighthouse PWA Audits

Procedure

Add web app manifest to the project
Implement the service worker with appropriate registration
Choose and apply caching strategies for assets and API calls
Implement offline support with fallback pages and queued actions
Review sample PWA setup for a complete React + Vite example
Add install prompt handling (see Install Prompt below)
Test with Lighthouse PWA audit — target 100 score
Validate on multiple devices (mobile, tablet, desktop)

Core Architecture

┌────────────────────────────────────────────┐
│                  Browser                    │
│  ┌──────────────────────────────────────┐  │
│  │            App Shell                  │  │
│  │  (HTML + CSS + JS — cached locally)   │  │
│  └──────────────┬───────────────────────┘  │
│                 │                           │
│  ┌──────────────▼───────────────────────┐  │
│  │         Service Worker                │  │
│  │  ┌───────────┐  ┌─────────────────┐  │  │
│  │  │ Precache  │  │ Runtime Cache   │  │  │
│  │  │ (static)  │  │ (API + dynamic) │  │  │
│  │  └───────────┘  └─────────────────┘  │  │
│  └──────────────┬───────────────────────┘  │
│                 │                           │
└─────────────────┼──────────────────────────┘
                  │
          ┌───────▼───────┐
          │    Network     │
          │  (origin API)  │
          └───────────────┘

Quick Reference — PWA Checklist

Install Prompt

Handle the beforeinstallprompt event to show a custom install UI:

// hooks/useInstallPrompt.ts
import { useState, useEffect, useCallback } from 'react';

interface BeforeInstallPromptEvent extends Event {
  prompt(): Promise<void>;
  userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>;
}

export function useInstallPrompt() {
  const [installPrompt, setInstallPrompt] =
    useState<BeforeInstallPromptEvent | null>(null);
  const [isInstalled, setIsInstalled] = useState(false);

  useEffect(() => {
    const handler = (e: Event) => {
      e.preventDefault();
      setInstallPrompt(e as BeforeInstallPromptEvent);
    };

    const installedHandler = () => setIsInstalled(true);

    window.addEventListener('beforeinstallprompt', handler);
    window.addEventListener('appinstalled', installedHandler);

    // Check if already installed
    if (window.matchMedia('(display-mode: standalone)').matches) {
      setIsInstalled(true);
    }

    return () => {
      window.removeEventListener('beforeinstallprompt', handler);
      window.removeEventListener('appinstalled', installedHandler);
    };
  }, []);

  const promptInstall = useCallback(async () => {
    if (!installPrompt) return false;
    await installPrompt.prompt();
    const { outcome } = await installPrompt.userChoice;
    setInstallPrompt(null);
    return outcome === 'accepted';
  }, [installPrompt]);

  return { canInstall: !!installPrompt, isInstalled, promptInstall };
}

Push Notifications

// utils/pushNotifications.ts
export async function subscribeToPush(
  vapidPublicKey: string
): Promise<PushSubscription | null> {
  if (!('PushManager' in window)) return null;

  const registration = await navigator.serviceWorker.ready;
  const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: urlBase64ToUint8Array(vapidPublicKey),
  });

  return subscription;
}

function urlBase64ToUint8Array(base64String: string): Uint8Array {
  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
  const base64 = (base64String + padding)
    .replace(/-/g, '+')
    .replace(/_/g, '/');
  const rawData = atob(base64);
  return Uint8Array.from(rawData, (char) => char.charCodeAt(0));
}

Framework Integration

React + Vite (vite-plugin-pwa)

npm install -D vite-plugin-pwa

// vite.config.ts
import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'autoUpdate',
      includeAssets: ['favicon.ico', 'robots.txt', 'apple-touch-icon.png'],
      manifest: {
        name: 'My App',
        short_name: 'App',
        description: 'My Progressive Web App',
        theme_color: '#ffffff',
        background_color: '#ffffff',
        display: 'standalone',
        scope: '/',
        start_url: '/',
        icons: [
          { src: 'pwa-192x192.png', sizes: '192x192', type: 'image/png' },
          { src: 'pwa-512x512.png', sizes: '512x512', type: 'image/png' },
          {
            src: 'pwa-512x512.png',
            sizes: '512x512',
            type: 'image/png',
            purpose: 'any maskable',
          },
        ],
      },
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
        runtimeCaching: [
          {
            urlPattern: /^https:\/\/api\./i,
            handler: 'NetworkFirst',
            options: {
              cacheName: 'api-cache',
              expiration: { maxEntries: 100, maxAgeSeconds: 60 * 60 },
              networkTimeoutSeconds: 10,
            },
          },
        ],
      },
    }),
  ],
});

Angular (@angular/service-worker)

ng add @angular/pwa

This generates ngsw-config.json, manifest.webmanifest, and registers the SW in app.module.ts. Customize caching groups in ngsw-config.json.

Completion Checklist

[ ] manifest.json present with name, short_name, icons, display, start_url, theme_color
[ ] Service worker registered and controlling the page
[ ] Static assets precached (HTML, CSS, JS, fonts, icons)
[ ] API responses cached with appropriate strategy
[ ] Offline fallback page served when network is unavailable
[ ] Install prompt handled with custom UI
[ ] Icons provided: 192×192 and 512×512 (plus maskable variant)
[ ] <meta name="theme-color"> set in HTML <head>
[ ] <meta name="viewport"> set for responsive layout
[ ] HTTPS configured (required for service workers)
[ ] Lighthouse PWA audit score = 100
[ ] Tested on mobile (iOS Safari, Android Chrome) and desktop

Adoption

congiuluc/pwa

$ install --global

Security Scan Results

SKILL.md

Progressive Web App (PWA)

When to Use

Official Documentation

Procedure

Core Architecture

Quick Reference — PWA Checklist

Install Prompt

Push Notifications

Framework Integration

React + Vite (vite-plugin-pwa)

Angular (@angular/service-worker)

Completion Checklist

Related Skills

congiuluc/vscode-extension

congiuluc/version-tracking

congiuluc/testing-frontend

congiuluc/testing-frontend-angular

congiuluc/pwa

$ install --global

Security Scan Results

SKILL.md

Progressive Web App (PWA)

When to Use

Official Documentation

Procedure

Core Architecture

Quick Reference — PWA Checklist

Install Prompt

Push Notifications

Framework Integration

React + Vite (vite-plugin-pwa)

Angular (@angular/service-worker)

Completion Checklist

Related Skills

congiuluc/vscode-extension

congiuluc/version-tracking

congiuluc/testing-frontend

congiuluc/testing-frontend-angular