/web-pwa-offline-first

name: web-pwa-offline-first
description: Local-first architecture with sync queues

Offline-First Application Patterns

> **Quick Guide:** Build applications that work primarily with local data, treating network connectivity as an enhancement. Use IndexedDB (via Dexie.js 4.x or idb 8.x) as the single source of truth. Implement sync queues for reliable background synchronization. Use optimistic UI patterns for instant feedback. Note: Background Sync API is experimental with limited browser support (Chrome/Edge only).

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use IndexedDB (via wrapper library) as the single source of truth for all offline data)**

**(You MUST implement sync metadata (\_syncStatus, \_lastModified, \_localVersion) on ALL entities that need synchronization)**

**(You MUST queue mutations during offline and process them when connectivity returns)**

**(You MUST use soft deletes (tombstones) for deletions to enable proper sync across devices)**

**(You MUST implement exponential backoff with jitter for ALL sync retry logic)**

**(You MUST NOT await non-IndexedDB operations mid-transaction - transactions auto-close when control returns to event loop)**

</critical_requirements>

---

**Auto-detection:** offline-first, IndexedDB, Dexie, idb, sync queue, local-first, offline storage, background sync, optimistic UI offline, conflict resolution, CRDT, last-write-wins

**When to use:**

• Building applications that must work without network connectivity
• Field service apps with poor or intermittent connectivity
• Note-taking or productivity apps requiring instant responsiveness
• Apps where data ownership and local-first architecture is prioritized
• Progressive Web Apps (PWAs) needing robust offline support

**When NOT to use:**

• Real-time dashboards requiring always-fresh server data
• Financial transactions requiring immediate server confirmation
• Simple read-only apps where cache-first is sufficient
• Apps where offline capability adds no user value

**Storage Considerations:**

• IndexedDB: Up to 50% of available disk space (typically 1GB+), async, supports complex queries
• LocalStorage: Limited to 5MB per origin, synchronous (blocks UI), simple key-value only
• Safari: 7-day cap on script-writable storage (IndexedDB, Cache API) may evict data

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Syncable entities, repository pattern, sync queue, network detection, optimistic UI, connection-aware fetching
• [examples/indexeddb.md](examples/indexeddb.md) - Dexie.js setup, CRUD hooks, idb alternative, migrations, multi-tab coordination, quota management
• [examples/sync.md](examples/sync.md) - LWW resolution, field-level merge, conflict UI, version vectors, delta sync, background sync, pull-push strategy, sync indicators
• [reference.md](reference.md) - Decision frameworks, anti-patterns, troubleshooting

---

<philosophy>

Philosophy

Offline-first is a design philosophy where applications are built to work primarily with local data, treating network connectivity as an enhancement rather than a requirement.

**Core Principles:**

1. **Local is the Source of Truth:** The local database is always authoritative. All reads and writes go through local storage first. Server sync happens in the background.

2. **Immediate Responsiveness:** Users never wait for network operations. Changes are applied locally instantly, synced later.

3. **Graceful Degradation:** Apps work fully offline, enhance when online, and handle transitions seamlessly.

4. **Sync Transparency:** Users understand their data's sync state through clear UI indicators without technical jargon.

**The Offline-First Data Flow:**

User Action
    |
Local Database (IndexedDB) <-- Single Source of Truth
    |
UI Updates Immediately (Optimistic)
    |
Sync Queue (Background)
    |
Server (When Online)
    |
Conflict Resolution (If Needed)
    |
Local Database Updated

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Syncable Entity Structure

Every entity that needs synchronization must include metadata for tracking sync state. This is the foundational pattern - all other patterns depend on it.

interface SyncableEntity {
  id: string;
  _syncStatus: "synced" | "pending" | "conflicted";
  _lastModified: number;
  _serverTimestamp?: number;
  _localVersion: string;
  _serverVersion?: string;
  _deletedAt?: number; // Soft delete tombstone
}

**Why this matters:** Without sync metadata, you cannot track what needs syncing, detect conflicts, or implement soft deletes. See [examples/core.md](examples/core.md) Pattern 1 for full implementation with factory functions.

---

Pattern 2: Repository Pattern

Use a repository as the single access point for all data operations, encapsulating local storage and sync queue logic. All reads come from local DB, all writes save locally first then queue for sync.

interface DataRepository<T extends SyncableEntity> {
  get(id: string): Promise<T | null>;
  getAll(): Promise<T[]>;
  save(item: T): Promise<void>; // Local write + queue sync
  delete(id: string): Promise<void>; // Soft delete + queue sync
  getPendingCount(): Promise<number>;
}

**Why this matters:** Encapsulates the local-first write pattern (save locally, queue for sync) so consumers don't need to manage both operations. See [examples/core.md](examples/core.md) Pattern 2 for full implementation.

---

Pattern 3: Sync Queue with Retry

Queue operations when offline, process reliably with exponential backoff when connectivity returns.

const MAX_RETRY_ATTEMPTS = 5;
const INITIAL_BACKOFF_MS = 1000;
const MAX_BACKOFF_MS = 30000;

function calculateBackoff(attempt: number): number {
  const exponentialDelay = Math.min(
    INITIAL_BACKOFF_MS * Math.