Pwa

PWA — Progressive Web App Checklist

Everything needed for a perfect Lighthouse PWA score and real-world installability.

Manifest (manifest.webmanifest)

Minimum viable:

{
  "name": "My App",
  "short_name": "App",
  "description": "What it does in one line.",
  "id": "/",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait",
  "theme_color": "#000000",
  "background_color": "#000000",
  "categories": ["productivity"],
  "icons": [
    { "src": "pwa-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
    { "src": "pwa-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
    { "src": "pwa-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
    { "src": "pwa-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

Icon Rules

• Minimum: 192×192 + 512×512 PNG
• Never combine "purpose": "any maskable" — split into separate entries. Combined works technically but Lighthouse flags it and maskable icons need safe-zone padding that looks bad as any.
• Maskable safe zone: Content must fit in center 80% circle. Test at https://maskable.app
• Favicon: Also provide a 196×196 PNG favicon and 180×180 Apple touch icon separately.
• SVG icon (optional, best quality): { "src": "icon.svg", "type": "image/svg+xml", "sizes": "any" }

id Field

Set "id": "/" — Chrome uses this to identify the installed PWA. Without it, changing start_url creates a "different" app.

display Options

HTML Head — Complete Template

<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
<meta name="description" content="..." />
<meta name="theme-color" content="#000000" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<meta name="apple-mobile-web-app-title" content="App Name" />
<meta name="mobile-web-app-capable" content="yes" />
<meta name="msapplication-TileColor" content="#000000" />
<meta name="msapplication-TileImage" content="/mstile-150x150.png" />

<link rel="icon" type="image/png" sizes="196x196" href="/favicon-196.png" />
<link rel="apple-touch-icon" href="/apple-icon-180.png" />
<link rel="mask-icon" href="/safari-pinned-tab.svg" color="#000000" />
<link rel="manifest" href="/manifest.webmanifest" />

What Each Does

Dark/Light Theme Color

<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)" />
<meta name="theme-color" content="#000000" media="(prefers-color-scheme: dark)" />

Apple Splash Screens

iOS shows a splash screen when launching from home screen. Without these, users see a white flash.

Generate with https://progressier.com/pwa-icons-and-ios-splash-screen-generator or similar tools.

<!-- iPhone SE / 8 -->
<link rel="apple-touch-startup-image" media="(device-width:320px) and (device-height:568px) and (-webkit-device-pixel-ratio:2)" href="/splash-640-1136.jpg" />
<link rel="apple-touch-startup-image" media="(device-width:375px) and (device-height:667px) and (-webkit-device-pixel-ratio:2)" href="/splash-750-1334.jpg" />
<!-- iPhone X / 11 Pro / 12 mini -->
<link rel="apple-touch-startup-image" media="(device-width:375px) and (device-height:812px) and (-webkit-device-pixel-ratio:3)" href="/splash-1125-2436.jpg" />
<!-- iPhone 12 / 13 / 14 -->
<link rel="apple-touch-startup-image" media="(device-width:390px) and (device-height:844px) and (-webkit-device-pixel-ratio:3)" href="/splash-1170-2532.jpg" />
<!-- iPhone 14 Pro / 15 -->
<link rel="apple-touch-startup-image" media="(device-width:393px) and (device-height:852px) and (-webkit-device-pixel-ratio:3)" href="/splash-1179-2556.jpg" />
<!-- iPhone Plus / Max -->
<link rel="apple-touch-startup-image" media="(device-width:414px) and (device-height:736px) and (-webkit-device-pixel-ratio:3)" href="/splash-1242-2208.jpg" />
<link rel="apple-touch-startup-image" media="(device-width:414px) and (device-height:896px) and (-webkit-device-pixel-ratio:3)" href="/splash-1242-2688.jpg" />
<link rel="apple-touch-startup-image" media="(device-width:428px) and (device-height:926px) and (-webkit-device-pixel-ratio:3)" href="/splash-1284-2778.jpg" />
<link rel="apple-touch-startup-image" media="(device-width:430px) and (device-height:932px) and (-webkit-device-pixel-ratio:3)" href="/splash-1290-2796.jpg" />
<!-- iPad -->
<link rel="apple-touch-startup-image" media="(device-width:768px) and (device-height:1024px) and (-webkit-device-pixel-ratio:2)" href="/splash-1536-2048.jpg" />
<link rel="apple-touch-startup-image" media="(device-width:810px) and (device-height:1080px) and (-webkit-device-pixel-ratio:2)" href="/splash-1620-2160.jpg" />
<link rel="apple-touch-startup-image" media="(device-width:834px) and (device-height:1112px) and (-webkit-device-pixel-ratio:2)" href="/splash-1668-2224.jpg" />
<link rel="apple-touch-startup-image" media="(device-width:834px) and (device-height:1194px) and (-webkit-device-pixel-ratio:2)" href="/splash-1668-2388.jpg" />
<link rel="apple-touch-startup-image" media="(device-width:1024px) and (device-height:1366px) and (-webkit-device-pixel-ratio:2)" href="/splash-2048-2732.jpg" />

Tip: Dark splash + app background = no flash. Use .jpg not .png (smaller).

Service Worker

Minimum Viable (Workbox)

import { cleanupOutdatedCaches, precacheAndRoute } from "workbox-precaching";
import { NavigationRoute, registerRoute } from "workbox-routing";
import { createHandlerBoundToURL } from "workbox-precaching";

declare let self: ServiceWorkerGlobalScope;

self.addEventListener("message", (event) => {
  if (event.data?.type === "SKIP_WAITING") self.skipWaiting();
});

precacheAndRoute(self.__WB_MANIFEST);
cleanupOutdatedCaches();
registerRoute(new NavigationRoute(createHandlerBoundToURL("index.html")));

Registration + Update Prompt

import { registerSW } from "virtual:pwa-register";

registerSW({
  onNeedRefresh() {
    if (confirm("New version available. Reload?")) location.reload();
  },
  onOfflineReady() {
    console.log("Ready to work offline");
  },
});

Runtime Caching (API calls, images)

import { registerRoute } from "workbox-routing";
import { StaleWhileRevalidate, CacheFirst } from "workbox-strategies";
import { ExpirationPlugin } from "workbox-expiration";

// Cache API responses — serve stale, revalidate in background
registerRoute(
  ({ url }) => url.pathname.startsWith("/api/"),
  new StaleWhileRevalidate({ cacheName: "api", plugins: [new ExpirationPlugin({ maxEntries: 50, maxAgeSeconds: 86400 })] })
);

// Cache images — cache first, expire after 30 days
registerRoute(
  ({ request }) => request.destination === "image",
  new CacheFirst({ cacheName: "images", plugins: [new ExpirationPlugin({ maxEntries: 100, maxAgeSeconds: 30 * 86400 })] })
);

vite-plugin-pwa Setup

pnpm add -D vite-plugin-pwa
pnpm add workbox-precaching workbox-routing workbox-window

injectManifest (recommended — full control)

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

export default defineConfig({
  plugins: [
    VitePWA({
      strategies: "injectManifest",
      srcDir: "src",
      filename: "sw.ts",
      manifest: { /* ... manifest fields ... */ },
    }),
  ],
});

Write your own src/sw.ts (see above).

generateSW (zero config — less control)

VitePWA({
  strategies: "generateSW",
  registerType: "autoUpdate",
  manifest: { /* ... */ },
  workbox: {
    globPatterns: ["**/*.{js,css,html,png,svg,woff2}"],
    runtimeCaching: [
      { urlPattern: /^https:\/\/api\./, handler: "StaleWhileRevalidate", options: { cacheName: "api" } },
    ],
  },
})

Install Prompt (A2HS)

let deferredPrompt: BeforeInstallPromptEvent | null = null;

window.addEventListener("beforeinstallprompt", (e) => {
  e.preventDefault();
  deferredPrompt = e;
  showInstallButton(); // your UI
});

async function install() {
  if (!deferredPrompt) return;
  deferredPrompt.prompt();
  const { outcome } = await deferredPrompt.userChoice;
  console.log(outcome === "accepted" ? "Installed" : "Dismissed");
  deferredPrompt = null;
}

// Detect if already installed
window.addEventListener("appinstalled", () => {
  hideInstallButton();
});

// Check display mode
const isInstalled = window.matchMedia("(display-mode: standalone)").matches
  || (navigator as any).standalone === true;

iOS caveat: beforeinstallprompt doesn't fire on iOS. Check navigator.standalone and show manual "Add to Home Screen" instructions.

Offline Page (optional)

For apps that can't fully work offline, serve a custom offline page:

// In sw.ts — catch navigation failures
import { setCatchHandler } from "workbox-routing";

setCatchHandler(async ({ event }) => {
  if (event.request.destination === "document") {
    return caches.match("/offline.html");
  }
  return Response.error();
});

Pre-cache offline.html in your manifest.

Nginx Gotchas

# Serve manifest with correct MIME type
location /manifest.webmanifest {
    types { application/manifest+json webmanifest; }
    expires 1d;
}

# Service worker must NOT be cached aggressively
location /sw.js {
    expires off;
    add_header Cache-Control "no-store, no-cache, must-revalidate";
}

# Cache static assets
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2|json|webmanifest)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

⚠️ The general static cache rule above would cache sw.js for 30 days. Always put the sw.js no-cache rule first, or exclude it from the pattern.

Icon Generation

From a single source PNG (≥ 512×512):

# Using ImageMagick
convert icon.png -resize 192x192 public/pwa-192x192.png
convert icon.png -resize 512x512 public/pwa-512x512.png
convert icon.png -resize 180x180 public/apple-icon-180.png
convert icon.png -resize 196x196 public/favicon-196.png
convert icon.png -resize 150x150 public/mstile-150x150.png

# Using sips (macOS)
sips -z 192 192 icon.png --out public/pwa-192x192.png
sips -z 512 512 icon.png --out public/pwa-512x512.png
sips -z 180 180 icon.png --out public/apple-icon-180.png
sips -z 196 196 icon.png --out public/favicon-196.png

Splash screens:

Use https://progressier.com/pwa-icons-and-ios-splash-screen-generator — upload one icon, get all sizes.

Or script it:

# Dark splash: centered icon on solid background
convert -size 1170x2532 xc:#000000 icon.png -gravity center -composite splash-1170-2532.jpg

Lighthouse PWA Audit Checklist

Quick Local Audit

# Lighthouse CLI
npx lighthouse https://localhost:5173 --only-categories=pwa --view

# Or in Chrome DevTools:
# Application tab → Manifest (check all green)
# Application tab → Service Workers (check registered)
# Lighthouse tab → PWA category

Debugging