PWA Installation & Add to Homescreen
debt(d3/e3/b3/t7)
Closest to 'default linter catches the common case' (d3) — Lighthouse (listed in detection_hints.tools) automatically audits PWA installability criteria (manifest, service worker, HTTPS, icons) and flags missing pieces clearly.
Closest to 'simple parameterised fix' (e3) — quick_fix is adding a manifest.json with required fields plus registering a service worker; it's more than one line but localised to a small set of static assets and a registration script.
Closest to 'localised tax' (b3) — applies_to is web context only; the manifest and service worker are isolated artifacts that don't shape the rest of the app architecture, though they do require ongoing maintenance of icons/start_url.
Closest to 'serious trap' (t7) — misconception explicitly states devs assume install happens automatically once criteria are met, but you must capture beforeinstallprompt and trigger UI yourself; plus iOS Safari doesn't fire the event at all, contradicting cross-browser expectations.
Also Known As
TL;DR
Explanation
PWA installation criteria (Chrome): HTTPS, registered service worker, valid Web App Manifest (name, icons 192px+512px, start_url, display: standalone). The beforeinstallprompt event fires when the browser decides the app is installable — capture it to show a custom install button rather than relying on the browser's default banner. iOS: does not support the beforeinstallprompt event — you must show manual instructions. Installed PWAs: get their own window, appear in task switcher, have their own icon, and can be launched from home screen without browser UI.
Watch Out
Common Misconception
Why It Matters
Common Mistakes
- Not handling iOS separately — Safari does not support beforeinstallprompt; show a manual instruction banner.
- manifest start_url not served by service worker — breaks offline functionality after installation.
- Icons not including 512px — required for Chrome install prompt.
- Showing install prompt too early — capture the event, but show the UI after demonstrating value.
Code Examples
// Missing manifest fields — not installable:
// manifest.json:
{
"name": "My App"
// Missing: icons, start_url, display, theme_color
}
// Result: browser never fires beforeinstallprompt// Complete manifest:
// manifest.json:
{
"name": "CodeClarityLab Glossary",
"short_name": "Glossary",
"start_url": "/glossary/?source=pwa",
"display": "standalone",
"theme_color": "#1a1a2e",
"background_color": "#1a1a2e",
"icons": [
{"src": "/icons/192.png", "sizes": "192x192", "type": "image/png"},
{"src": "/icons/512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable"}
]
}
// Custom install button:
let deferredPrompt;
window.addEventListener('beforeinstallprompt', e => {
e.preventDefault();
deferredPrompt = e;
document.getElementById('install-btn').hidden = false;
});
document.getElementById('install-btn').addEventListener('click', () => {
deferredPrompt.prompt();
});