Building Offline-First Web Apps: Sync Engines with IndexedDB and CRDTs

Modern applications frequently run on mobile devices with unstable internet connections. If your application displays a loading spinner or fails to save changes when the user loses connectivity, they will quickly abandon it. Building offline-first web applications allows users to continue working without interruption, syncing changes back to the database once connectivity is restored. In this guide, we analyze sync structures and construct a local sync engine using IndexedDB and CRDTs.

The Challenge of Offline State Synchronization

Building offline-first applications requires shifting the primary source of truth from the cloud database to the user's local device. This introduces several engineering challenges:

• Local Persistence: You must store database records securely on the client device using browser storage APIs like IndexedDB.
• Change Tracking: You must track local modifications when offline, queuing them in order until a connection is available.
• Conflict Resolution: When multiple clients modify the same record offline, you need a way to merge their updates without losing data.

We deploy these resilient offline-first patterns daily across our custom software development projects to ensure application stability.

Conflict Resolution: CRDTs vs. LWW

When syncing offline updates, developers must choose a conflict resolution strategy:

• Last-Write-Wins (LWW): Compares the timestamps of conflicting updates and keeps the newest one. LWW is simple to set up, but it is prone to data loss if user device clocks drift out of sync.
• Conflict-Free Replicated Data Types (CRDTs): Mathematical structures that merge conflicting updates deterministically, ensuring all devices converge on the same state without requiring a central coordinator. CRDTs are necessary for collaborative editors and shared task lists.

Implementing an Offline-First Sync Engine

Below is a production-grade sync engine written in TypeScript. It persists data locally in IndexedDB and uses a logical transaction log to sync updates with a remote server:

interface SyncMutation {
  id: string;
  table: string;
  action: 'INSERT' | 'UPDATE' | 'DELETE';
  payload: any;
  timestamp: number;
}

export class OfflineSyncEngine {
  private dbName = 'app_local_db';
  private syncQueueTable = 'sync_queue';

  async queueMutation(mutation: Omit<SyncMutation, 'timestamp'>): Promise<void> {
    const db = await this.openDatabase();
    const tx = db.transaction(this.syncQueueTable, 'readwrite');
    const store = tx.objectStore(this.syncQueueTable);
    
    await store.add({
      ...mutation,
      timestamp: Date.now()
    });
    console.log(`✓ Mutation queued locally: ${mutation.action} on ${mutation.table}`);
  }

  async syncWithServer(serverUrl: string): Promise<void> {
    const db = await this.openDatabase();
    const tx = db.transaction(this.syncQueueTable, 'readwrite');
    const store = tx.objectStore(this.syncQueueTable);
    const mutations: SyncMutation[] = await store.getAll();

    if (mutations.length === 0) {
      console.log('✓ Local database is already in sync with server.');
      return;
    }

    try {
      const response = await fetch(`${serverUrl}/api/sync`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ mutations })
      });

      if (response.ok) {
        // Clear queue upon successful server synchronization
        await store.clear();
        console.log('✓ Database synchronization completed successfully.');
      } else {
        throw new Error('Server rejected mutation payload');
      }
    } catch (err) {
      console.warn('❌ Synchronization failed: Database offline. Retry scheduled.', err);
    }
  }

  private openDatabase(): Promise<any> {
    return new Promise((resolve, reject) => {
      const request = indexedDB.open(this.dbName, 1);
      request.onupgradeneeded = () => {
        request.result.createObjectStore(this.syncQueueTable, { keyPath: 'id' });
      };
      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
  }
}

Handling Network Outages and Reconnections

A reliable sync engine must monitor network status dynamically to trigger synchronization cycles when the connection is restored. We implement this using browser connection events:

export class NetworkMonitor {
  constructor(private syncEngine: OfflineSyncEngine, private serverUrl: string) {
    this.registerConnectionListeners();
  }

  private registerConnectionListeners() {
    window.addEventListener('online', () => {
      console.log('📶 Device back online. Initiating sync...');
      this.syncEngine.syncWithServer(this.serverUrl);
    });

    window.addEventListener('offline', () => {
      console.warn('📶 Device disconnected. Working in offline mode.');
    });
  }
}

Step-by-Step Offline-First Production Implementation Checklist

Configure offline-first synchronizations using this structured checklist:

1. Define Local Database Schema: Setup your IndexedDB tables using lightweight database wrappers (e.g., Dexie.js).
2. Implement Mutation Tracking: Wrap all database write operations in transaction hooks that record changes to a local sync table.
3. Build Queue Managers: Write managers to execute queued mutations sequentially when network connections are restored.
4. Choose Conflict Strategy: Select between timestamp-based LWW or mathematically mergeable CRDT objects.
5. Configure Server Reconciliation Routes: Set up API endpoints to validate incoming mutation queues and apply updates.
6. Implement Client Listeners: Listen to browser connection events to pause and resume synchronization processes automatically.
7. Design Conflict Dashboards: Create user dashboards to resolve complex merge conflicts manually when needed.
8. Optimize Storage Limits: Periodically prune older mutation logs to stay within browser storage allocations.
9. Implement Retry Backoffs: Use exponential backoff strategies to prevent overloading servers when reconnecting.
10. Run Local Data Tests: Validate your sync flows using end-to-end testing frameworks under simulated offline conditions.

Summary of Recommendations

Building offline-first web applications requires combining local IndexedDB storage with structured sync engines. Enforcing these local guardrails ensures your application remains responsive and functional under any network conditions.

Data Persistence & Offline Operations (Deep-Dive Analysis #1): Architectural Strategy

Persisting data locally requires understanding browser storage limits and eviction rules. Browsers allocate storage dynamically based on available disk space, and may delete IndexedDB tables if disk space is low. To prevent data loss, developers should request persistent storage permissions from the browser. This request prompts the user to grant storage permissions that protect local tables from automatic eviction during system cleanups.

Data Persistence & Offline Operations (Deep-Dive Analysis #2): Operational Guidelines

Additionally, offline-first sync engines must handle large mutation payloads efficiently. When a device remains offline for days, the queue of local changes can grow to thousands of operations. Sending this entire queue to the server in a single payload can cause timeouts. We address this by chunking mutation logs into smaller batches, syncing them sequentially, and validating each batch before sending the next. This configuration stabilizes the synchronization process and ensures data convergence.

Mathematical Modeling Analysis

To guarantee that client states merge consistently, we represent database tables as state-based CRDTs. Each record is configured with a vector clock representing updates across different client sessions. The merge function resolves differences by calculating the mathematical maximum value of each clock index. This operation is commutative, associative, and idempotent, ensuring that all devices converge on the same state regardless of network order.