{
    "slug": "app_shell_architecture",
    "term": "App Shell Architecture",
    "category": "mobile",
    "difficulty": "intermediate",
    "short": "Caching the minimal HTML, CSS, and JS needed to display the UI skeleton on first load — so the shell renders instantly from cache while dynamic content loads from the network.",
    "long": "The App Shell model separates the application shell (header, navigation, skeleton layout) from the content. The shell is cached by the service worker on first visit — subsequent visits render the shell instantly from cache (< 100ms) while content fetches from the network. Benefits: reliable fast first paint, works offline for the shell, and progressively enhances with content. Implemented with Service Worker precaching. Works well for: SPAs, PWAs, and any app with a consistent chrome around changing content. Not suited for: content-first sites where every page has a unique layout.",
    "aliases": [
        "app shell",
        "shell caching",
        "instant loading"
    ],
    "tags": [
        "mobile",
        "pwa",
        "performance",
        "service-worker"
    ],
    "misconception": "App shell architecture requires a SPA framework — it is a caching strategy implementable with any frontend approach; even a PHP-rendered site can cache the navigation shell via service worker.",
    "why_it_matters": "A 3G user visiting a PWA without app shell waits 4 seconds for the first paint — with app shell, the navigation renders in under 100ms from cache while content loads.",
    "common_mistakes": [
        "Including dynamic content in the app shell — the shell should only contain stable UI chrome.",
        "No fallback for content fetch failure — offline shell with no content is a bad experience without a fallback page.",
        "Shell too large — cache only the critical rendering path, not the entire application.",
        "Not versioning the shell cache — stale shells serve outdated UI after deploys."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "service_worker_caching",
        "progressive_web_apps",
        "web_vitals",
        "offline_first_design"
    ],
    "prerequisites": [
        "progressive_web_apps",
        "service_worker_caching",
        "js_history_api"
    ],
    "refs": [
        "https://web.dev/articles/app-shell"
    ],
    "bad_code": "// No shell caching — full page re-download on every visit:\n// index.html: 45KB (header + nav + content + footer all mixed)\n// On 3G: 4 second first paint, every visit\n// Offline: nothing works",
    "good_code": "// Service worker precaches the shell:\nconst SHELL = [\n    '/shell.html',    // Minimal HTML skeleton\n    '/app.css',       // Critical styles\n    '/app.js',        // Core JS\n    '/icons/logo.svg',\n];\n\nself.addEventListener('install', e => {\n    e.waitUntil(caches.open('shell-v2').then(c => c.addAll(SHELL)));\n});\n\nself.addEventListener('fetch', e => {\n    // Serve shell instantly from cache:\n    if (SHELL.includes(new URL(e.request.url).pathname)) {\n        e.respondWith(caches.match(e.request));\n    }\n    // Content: network first, cache fallback\n});",
    "quick_fix": "Cache the app shell (header, nav, footer) in a service worker; PHP serves data via JSON APIs; JavaScript renders the content — this pattern enables instant repeat visits",
    "severity": "medium",
    "effort": "high",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/app_shell_architecture",
        "html_url": "https://codeclaritylab.com/glossary/app_shell_architecture",
        "json_url": "https://codeclaritylab.com/glossary/app_shell_architecture.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": "[App Shell Architecture](https://codeclaritylab.com/glossary/app_shell_architecture) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/app_shell_architecture"
            }
        }
    }
}