{
    "slug": "offline_first_design",
    "term": "Offline-First Design",
    "category": "mobile",
    "difficulty": "advanced",
    "short": "Designing applications to work without a network connection by default — storing data locally, syncing when online, and handling conflicts gracefully.",
    "long": "Offline-first assumes the network is unreliable — store everything locally first, then sync to the server when connectivity is available. Technologies: IndexedDB (client-side structured storage), Service Worker (intercept requests and serve from cache), Background Sync API (defer network requests until online), CRDTs (Conflict-free Replicated Data Types) for conflict-free merging. Patterns: optimistic updates (show change immediately, sync in background), conflict resolution (last-write-wins, server-wins, or manual merge), and sync queue (pending operations stored and retried).",
    "aliases": [
        "offline first",
        "local-first",
        "sync",
        "IndexedDB"
    ],
    "tags": [
        "mobile",
        "pwa",
        "architecture"
    ],
    "misconception": "Offline-first is only for mobile apps — any web app used in areas with poor connectivity (travel, remote work, field service) benefits from offline-first design.",
    "why_it_matters": "A field technician using a web app in a basement with no signal loses all unsaved work without offline-first — with it, they work normally and changes sync automatically when they return to signal.",
    "common_mistakes": [
        "No conflict resolution strategy — concurrent offline edits from multiple devices corrupt data.",
        "Storing sensitive data in IndexedDB without encryption — IndexedDB is not encrypted by default.",
        "No user feedback on sync status — users need to know when their data is saved vs pending sync.",
        "Offline-first for real-time features — chat and live collaboration require constant connectivity."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "progressive_web_apps",
        "app_shell_architecture",
        "service_worker_caching"
    ],
    "prerequisites": [
        "service_worker_caching",
        "progressive_enhancement",
        "js_indexeddb"
    ],
    "refs": [
        "https://offlinefirst.org/"
    ],
    "bad_code": "// No offline support — data lost when network drops:\nasync function saveNote(note) {\n    await fetch('/api/notes', {\n        method: 'POST',\n        body: JSON.stringify(note),\n    });\n    // If fetch fails: error, data lost, user frustrated\n}",
    "good_code": "// Offline-first: save locally, sync in background:\nasync function saveNote(note) {\n    const db = await openDB('notes-store', 1);\n    await db.put('notes', { ...note, synced: false }); // Save locally first\n    showUI('Saved locally');\n\n    if (navigator.onLine) {\n        await syncToServer(note);\n        await db.put('notes', { ...note, synced: true });\n        showUI('Synced');\n    } else {\n        // Background Sync: retry when online:\n        await navigator.serviceWorker.ready.then(sw =>\n            sw.sync.register('sync-notes')\n        );\n    }\n}",
    "quick_fix": "Design for offline first: store data locally with IndexedDB, sync with your PHP backend when connectivity returns, and show optimistic UI immediately — don't wait for server confirmation for every action",
    "severity": "medium",
    "effort": "high",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/offline_first_design",
        "html_url": "https://codeclaritylab.com/glossary/offline_first_design",
        "json_url": "https://codeclaritylab.com/glossary/offline_first_design.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": "[Offline-First Design](https://codeclaritylab.com/glossary/offline_first_design) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/offline_first_design"
            }
        }
    }
}