{
    "slug": "pwa_installation",
    "term": "PWA Installation & Add to Homescreen",
    "category": "mobile",
    "difficulty": "intermediate",
    "short": "Progressive Web Apps can be installed to the home screen like native apps — requiring HTTPS, a Web App Manifest, and a Service Worker, plus meeting browser-specific installation criteria.",
    "long": "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.",
    "aliases": [
        "add to homescreen",
        "beforeinstallprompt",
        "web app manifest",
        "PWA install"
    ],
    "tags": [
        "mobile",
        "pwa"
    ],
    "misconception": "PWA installation happens automatically once criteria are met — Chrome waits for user engagement before showing the install prompt; you must capture the beforeinstallprompt event and show your own UI at the right moment.",
    "why_it_matters": "Installed PWAs have 3x higher engagement than browser sessions — the home screen icon provides the same discoverability and re-engagement as a native app without the App Store friction.",
    "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."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "progressive_web_apps",
        "service_worker_caching",
        "app_shell_architecture"
    ],
    "prerequisites": [
        "service_worker_caching",
        "offline_first_design",
        "progressive_enhancement"
    ],
    "refs": [
        "https://web.dev/articles/customize-install"
    ],
    "bad_code": "// Missing manifest fields — not installable:\n// manifest.json:\n{\n    \"name\": \"My App\"\n    // Missing: icons, start_url, display, theme_color\n}\n// Result: browser never fires beforeinstallprompt",
    "good_code": "// Complete manifest:\n// manifest.json:\n{\n    \"name\": \"CodeClarityLab Glossary\",\n    \"short_name\": \"Glossary\",\n    \"start_url\": \"/glossary/?source=pwa\",\n    \"display\": \"standalone\",\n    \"theme_color\": \"#1a1a2e\",\n    \"background_color\": \"#1a1a2e\",\n    \"icons\": [\n        {\"src\": \"/icons/192.png\", \"sizes\": \"192x192\", \"type\": \"image/png\"},\n        {\"src\": \"/icons/512.png\", \"sizes\": \"512x512\", \"type\": \"image/png\", \"purpose\": \"any maskable\"}\n    ]\n}\n\n// Custom install button:\nlet deferredPrompt;\nwindow.addEventListener('beforeinstallprompt', e => {\n    e.preventDefault();\n    deferredPrompt = e;\n    document.getElementById('install-btn').hidden = false;\n});\ndocument.getElementById('install-btn').addEventListener('click', () => {\n    deferredPrompt.prompt();\n});",
    "quick_fix": "Add a web app manifest (manifest.json) with icons, name, and display: standalone — browsers show an 'Add to Home Screen' prompt when your PHP app meets the PWA installability criteria",
    "severity": "info",
    "effort": "medium",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/pwa_installation",
        "html_url": "https://codeclaritylab.com/glossary/pwa_installation",
        "json_url": "https://codeclaritylab.com/glossary/pwa_installation.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[PWA Installation & Add to Homescreen](https://codeclaritylab.com/glossary/pwa_installation) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/pwa_installation"
            }
        }
    }
}