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.
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();
});