Offline-First with Conflict Resolution

The Local-First Philosophy

Most web apps treat the server as the source of truth. Your device is a dumb terminal that fetches data, displays it, and sends changes back. If the server is unreachable, the app is useless.

Offline-first flips this: the device is the source of truth. Data lives locally. The UI reads from local storage. Changes are written locally first. Sync with the server happens in the background, when possible.

This isn't just about handling airplane mode. It's about fundamentally better UX:

• Instant responsiveness — every read and write is local, no network round trip
• Works everywhere — elevators, tunnels, spotty conference WiFi, airplane, subway
• Survives server outages — your server goes down, users don't even notice
• Reduces server load — the server handles sync, not every read/write

The challenge? When two devices edit the same data offline and then sync, you need conflict resolution.

IndexedDB as Primary Datastore

For offline-first web apps, IndexedDB is your database. Not a cache. Not a fallback. The primary datastore.

interface SyncableRecord {
  id: string;
  data: unknown;
  updatedAt: number;
  version: number;
  syncStatus: 'synced' | 'pending' | 'conflict';
  localChanges?: unknown;
}

class LocalStore {
  private db: IDBDatabase | null = null;

  async open(name: string, stores: string[]): Promise<void> {
    return new Promise((resolve, reject) => {
      const request = indexedDB.open(name, 1);
      request.onupgradeneeded = () => {
        const db = request.result;
        for (const store of stores) {
          if (!db.objectStoreNames.contains(store)) {
            const objectStore = db.createObjectStore(store, { keyPath: 'id' });
            objectStore.createIndex('syncStatus', 'syncStatus');
            objectStore.createIndex('updatedAt', 'updatedAt');
          }
        }
      };
      request.onsuccess = () => {
        this.db = request.result;
        resolve();
      };
      request.onerror = () => reject(request.error);
    });
  }

  async put(store: string, record: SyncableRecord): Promise<void> {
    return new Promise((resolve, reject) => {
      const tx = this.db!.transaction(store, 'readwrite');
      tx.objectStore(store).put(record);
      tx.oncomplete = () => resolve();
      tx.onerror = () => reject(tx.error);
    });
  }

  async get(store: string, id: string): Promise<SyncableRecord | undefined> {
    return new Promise((resolve, reject) => {
      const tx = this.db!.transaction(store, 'readonly');
      const request = tx.objectStore(store).get(id);
      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
  }

  async getPending(store: string): Promise<SyncableRecord[]> {
    return new Promise((resolve, reject) => {
      const tx = this.db!.transaction(store, 'readonly');
      const index = tx.objectStore(store).index('syncStatus');
      const request = index.getAll('pending');
      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
  }
}

Sync Protocols: Full State vs Delta

When the device comes back online, it needs to sync with the server. Two approaches:

Full State Sync

Send the entire local state. Server compares with its state, computes a merge, and returns the result.

async function fullStateSync(
  localStore: LocalStore,
  storeName: string,
  serverUrl: string
): Promise<void> {
  const tx = localStore.db!.transaction(storeName, 'readonly');
  const allRecords: SyncableRecord[] = await new Promise((resolve, reject) => {
    const request = tx.objectStore(storeName).getAll();
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });

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

  const { merged } = await response.json();
  for (const record of merged) {
    await localStore.put(storeName, { ...record, syncStatus: 'synced' });
  }
}

• Pros: Simple, always correct, handles any level of divergence
• Cons: Expensive for large datasets, wastes bandwidth on unchanged data

Delta Sync

Track what changed since the last sync. Only send and receive changes.

interface SyncCheckpoint {
  lastSyncTimestamp: number;
  lastServerVersion: number;
}

async function deltaSync(
  localStore: LocalStore,
  storeName: string,
  serverUrl: string,
  checkpoint: SyncCheckpoint
): Promise<SyncCheckpoint> {
  const pendingRecords = await localStore.getPending(storeName);

  const response = await fetch(`${serverUrl}/sync/delta`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      changes: pendingRecords,
      since: checkpoint.lastServerVersion,
    }),
  });

  const { serverChanges, newVersion, conflicts } = await response.json();

  for (const change of serverChanges) {
    const local = await localStore.get(storeName, change.id);
    if (local?.syncStatus === 'pending') {
      // Conflict: local change + server change
      await localStore.put(storeName, {
        ...local,
        syncStatus: 'conflict',
        localChanges: local.data,
        data: change.data,
      });
    } else {
      await localStore.put(storeName, { ...change, syncStatus: 'synced' });
    }
  }

  for (const record of pendingRecords) {
    if (!conflicts.includes(record.id)) {
      await localStore.put(storeName, { ...record, syncStatus: 'synced' });
    }
  }

  return {
    lastSyncTimestamp: Date.now(),
    lastServerVersion: newVersion,
  };
}

In practice, use delta sync as the default with full state sync as a fallback for first connection, long offline periods, or suspected data corruption.

Conflict Resolution Beyond Last-Writer-Wins

LWW is the simplest conflict resolution: the write with the latest timestamp wins. It works when:

• Conflicts are rare
• The data is not critical (user preferences, draft notes)
• Users expect "my latest change is what matters"

But LWW silently discards data. When Alice edits a task title while Bob edits the same task title offline, one of them loses their work. For many applications, this is unacceptable.

Field-Level Merge

Instead of LWW on the entire record, apply LWW per field:

interface FieldChange {
  field: string;
  value: unknown;
  timestamp: number;
}

function fieldLevelMerge(
  base: Record<string, unknown>,
  local: Record<string, FieldChange>,
  remote: Record<string, FieldChange>
): Record<string, unknown> {
  const result = { ...base };

  const allFields = new Set([...Object.keys(local), ...Object.keys(remote)]);

  for (const field of allFields) {
    const localChange = local[field];
    const remoteChange = remote[field];

    if (localChange && !remoteChange) {
      result[field] = localChange.value;
    } else if (!localChange && remoteChange) {
      result[field] = remoteChange.value;
    } else if (localChange && remoteChange) {
      result[field] = localChange.timestamp >= remoteChange.timestamp
        ? localChange.value
        : remoteChange.value;
    }
  }

  return result;
}

Alice changes the title, Bob changes the description — both changes survive. Only same-field concurrent edits need a tiebreaker.

Three-Way Merge

The gold standard for structured data. Compare local and remote states against a common ancestor (base) to detect exactly what each side changed:

type MergeResult =
  | { type: 'clean'; value: unknown }
  | { type: 'conflict'; base: unknown; local: unknown; remote: unknown };

function threeWayMerge(
  base: Record<string, unknown>,
  local: Record<string, unknown>,
  remote: Record<string, unknown>
): Map<string, MergeResult> {
  const results = new Map<string, MergeResult>();
  const allKeys = new Set([
    ...Object.keys(base),
    ...Object.keys(local),
    ...Object.keys(remote),
  ]);

  for (const key of allKeys) {
    const b = base[key];
    const l = local[key];
    const r = remote[key];

    const localChanged = !deepEqual(b, l);
    const remoteChanged = !deepEqual(b, r);

    if (!localChanged && !remoteChanged) {
      results.set(key, { type: 'clean', value: b });
    } else if (localChanged && !remoteChanged) {
      results.set(key, { type: 'clean', value: l });
    } else if (!localChanged && remoteChanged) {
      results.set(key, { type: 'clean', value: r });
    } else if (deepEqual(l, r)) {
      results.set(key, { type: 'clean', value: l });
    } else {
      results.set(key, { type: 'conflict', base: b, local: l, remote: r });
    }
  }

  return results;
}

function deepEqual(a: unknown, b: unknown): boolean {
  return JSON.stringify(a) === JSON.stringify(b);
}

Three-way merge gives you clean merges for the majority of cases and explicitly surfaces true conflicts — cases where both sides changed the same field to different values.

Eventual Consistency UX Patterns

The hardest part of offline-first isn't the sync protocol — it's communicating sync state to the user.

Optimistic UI with Sync Status

Show changes immediately. Indicate sync status subtly:

type SyncIndicator = 'saved-locally' | 'syncing' | 'synced' | 'conflict' | 'error';

interface UIRecord {
  data: unknown;
  syncStatus: SyncIndicator;
  lastSyncedAt: number | null;
  pendingSince: number | null;
}

Visual patterns that work:

• Cloud icon with checkmark: Synced
• Cloud icon with arrows: Syncing
• Cloud icon with offline symbol: Saved locally, will sync when online
• Warning triangle: Conflict needs attention

Conflict Resolution UX

When three-way merge detects a true conflict, you have options:

1. Automatic resolution with policy — LWW, or prefer-local, or prefer-remote. Silent but may lose data.
2. Show both versions — Let the user choose. Best for important data but interrupts workflow.
3. Merge and highlight — Auto-merge what you can, highlight conflicting fields. Best balance.

function renderConflict(
  field: string,
  result: MergeResult & { type: 'conflict' }
): ConflictUI {
  return {
    field,
    message: `This field was changed on both devices`,
    yourVersion: result.local,
    otherVersion: result.remote,
    originalVersion: result.base,
    actions: [
      { label: 'Keep yours', value: result.local },
      { label: 'Keep theirs', value: result.remote },
      { label: 'Keep both', value: mergeValues(result.local, result.remote) },
    ],
  };
}

Lessons From Production: Linear and Notion

Linear's Offline Mode

Linear is the gold standard for offline-first in a SaaS product. Their approach:

• Local SQLite (via WASM) as the primary datastore
• Delta sync with a server-maintained operation log
• Optimistic mutations — UI updates instantly, syncs in background
• Conflict resolution — field-level merge with LWW per field
• Partial sync — only sync data the user has access to (team/project scoping)

The key insight: Linear treats the server as a sync peer, not the source of truth. The client doesn't "ask permission" to make changes — it makes them locally and tells the server afterward.

Notion's Local-First Journey

Notion has been progressively moving toward local-first:

• Block-level CRDTs for document structure
• Local persistence for recently viewed pages
• Offline editing for pages that are cached locally
• Sync on reconnection with conflict detection

Their challenge is scale: a Notion workspace can have millions of blocks. You can't sync everything locally. The solution is partial replication — only sync the subset of data the user actively needs.

Building the Sync Engine

Putting it all together — a minimal but complete sync engine:

class SyncEngine {
  private syncTimer: ReturnType<typeof setInterval> | null = null;
  private isSyncing = false;

  constructor(
    private localStore: LocalStore,
    private storeName: string,
    private serverUrl: string,
    private checkpoint: SyncCheckpoint = { lastSyncTimestamp: 0, lastServerVersion: 0 }
  ) {}

  start(intervalMs = 5000): void {
    this.sync();
    this.syncTimer = setInterval(() => this.sync(), intervalMs);

    window.addEventListener('online', () => this.sync());
    document.addEventListener('visibilitychange', () => {
      if (document.visibilityState === 'visible') this.sync();
    });
  }

  async write(id: string, data: unknown): Promise<void> {
    const existing = await this.localStore.get(this.storeName, id);
    await this.localStore.put(this.storeName, {
      id,
      data,
      updatedAt: Date.now(),
      version: (existing?.version ?? 0) + 1,
      syncStatus: 'pending',
    });
  }

  private async sync(): Promise<void> {
    // Quick pre-check only — navigator.onLine is unreliable (see reconnection-and-offline-queueing)
    if (this.isSyncing || !navigator.onLine) return;
    this.isSyncing = true;

    try {
      this.checkpoint = await deltaSync(
        this.localStore,
        this.storeName,
        this.serverUrl,
        this.checkpoint
      );
    } catch {
      // Sync failed — will retry on next interval
    } finally {
      this.isSyncing = false;
    }
  }

  stop(): void {
    if (this.syncTimer) clearInterval(this.syncTimer);
  }
}