How do I fix Progressive Web App (PWA)?

Add manifest.json with name/icons/display:standalone, register a service worker in a , serve over HTTPS — Chrome Lighthouse shows exactly what is missing

← Back to glossary

Progressive Web App (PWA)

Mobile Intermediate

debt(d3/e3/b3/t5)

d3 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'default linter catches the common case' (d3), since Chrome Lighthouse audits (cited in quick_fix) explicitly report PWA criteria failures — manifest missing, service worker not registered, no HTTPS — as a standard audit tool runs.

e3 Effort Remediation debt — work required to fix once spotted

Closest to 'simple parameterised fix' (e3), since quick_fix is adding a manifest.json, registering a service worker, and serving over HTTPS — a small additive change in one component, not a one-line patch but not a refactor.

b3 Burden Structural debt — long-term weight of choosing wrong

Closest to 'localised tax' (b3), since the PWA layer (manifest + service worker) sits alongside the existing app and doesn't reshape the codebase; the service worker cache strategy can grow into a persistent tax but typically stays localised.

t5 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'notable trap' (t5), grounded in the misconception that PWAs require a JS framework, plus documented gotchas (install prompt timing, iOS needing separate apple-touch-icon, HTTPS requirement for service workers) that most devs only learn after hitting them.

About DEBT scoring → scored by claude-opus-4-7 · 2026-05-11 · reviewed by human

Also Known As

PWA progressive web application installable web app web app manifest

TL;DR

A web application that uses modern browser APIs to deliver app-like experiences — installable on the home screen, working offline, and receiving push notifications — without requiring an app store.

Explanation

A Progressive Web App is a web app that meets a set of technical criteria: served over HTTPS, includes a web app manifest (JSON file describing name, icons, theme colour, and display mode), and registers a service worker (a JavaScript file that intercepts network requests and manages caching). When these criteria are met, browsers on Android and iOS offer to install the app to the home screen, where it launches in standalone mode without browser chrome. PWAs progressively enhance — they work as normal websites in older browsers and as app-like experiences in modern ones. PHP backends serve PWAs like any other web application; the PWA layer is entirely frontend.

Common Misconception

✗ PWAs require a JavaScript framework like React or Vue. PWAs are a set of technical criteria applied to any web application regardless of frontend stack. A server-rendered PHP application can be a PWA by adding a manifest.json and a service worker script — no frontend framework required. The manifest and service worker are plain JSON and JavaScript files.

Why It Matters

PWAs close the gap between web and native apps for the majority of use cases where an app store presence is not essential. For PHP developers building customer-facing applications, PWA features directly improve engagement metrics — the install prompt increases return visit rates, offline support prevents abandonment during connectivity loss, and push notifications re-engage users without requiring an app store listing or per-platform native development. The investment is a manifest file and a service worker — both achievable in an afternoon.

Common Mistakes

Forgetting HTTPS — browsers will not register service workers on HTTP origins, making the PWA checklist impossible to pass.
Using a generic manifest without appropriate icons for each platform — iOS requires specific apple-touch-icon sizes in the HTML head separate from the manifest.
Not testing the install prompt — it only appears after the user has visited twice with a gap between visits, making it easy to miss in testing.
Skipping Lighthouse audit — Chrome DevTools Lighthouse gives a PWA score and lists exactly which criteria are failing.

Code Examples

✗ Vulnerable

<!-- Missing manifest link and HTTPS is assumed -->
<html>
<head>
    <title>My App</title>
    <!-- No manifest, no service worker registration -->
</head>

✓ Fixed

<!-- PWA-ready HTML head -->
<head>
    <title>My App</title>
    <link rel="manifest" href="/manifest.json">
    <meta name="theme-color" content="#6d28d9">
    <link rel="apple-touch-icon" href="/icons/icon-192.png">
</head>

// manifest.json
{
  "name": "My App",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#6d28d9",
  "icons": [{"src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png"}]
}

// Register service worker
if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/sw.js');
}

References

https://web.dev/progressive-web-apps/