Local-First Sync & CRDTs
Local-first apps read and write against local IndexedDB or OPFS at 0 ms, treating the server as a sync peer rather than a gatekeeper. Conflict-free Replicated Data Types (CRDTs) tag operations with (clientId, logicalClock) so concurrent offline edits converge to the exact same state regardless of arrival order.
Sync Architecture: Server-First LWW vs Local-First CRDT
Compare naive timestamp Last-Write-Wins overwrites against commutative CRDT state convergence.
// Offline client B overwrites client A's edits on reconnect
await fetch('/doc/1', {
method: 'PUT',
body: JSON.stringify({ content: fullText, updatedAt: Date.now() })
});Whichever laptop reconnects last wipes out the other user's offline paragraphs.
// Every edit writes locally at 0ms with a unique (clientId, lamportClock)
ydoc.transact(() => ytext.insert(cursor, 'hello'));
// Reconnect exchanges stateVector diffs; both peers converge identicallyConcurrent offline edits merge deterministically in any arrival order.
Under the Hood
Unlike Optimistic UI, where the server remains judge and jury and failed mutations roll back, a CRDT works like an append-only ledger with mathematical commutativity (merge(A, B) === merge(B, A)). Paired with a Service Worker for offline asset booting, the client never blocks on a round-trip.
- Local persistence: Edits commit immediately to IndexedDB or Origin Private File System (OPFS) in sub-millisecond transactions.
- Causal IDs: Each character or map key receives a unique Lamport/Hybrid Logical Clock
(clock, clientId)tuple, immune to skewed laptop system clocks. - State-vector sync: On reconnect, peers exchange compact version vectors and stream only missing operations, converging identically with zero central lock.
// Commutative LWW-Register merge: order-independent convergence
function mergeRegister(local, remote) {
if (remote.hlc > local.hlc) return remote;
if (remote.hlc === local.hlc && remote.clientId > local.clientId) return remote;
return local;
}Problem Genealogy
- 2006 (Operational Transformation, Google Docs): Transformed concurrent cursor indices on a central server, notorious for subtle convergence bugs off-server.
- 2011 (Shapiro et al. CRDTs): Proved algebraic semilattice properties guaranteeing lock-free peer convergence.
- 2019+ (Local-First Software, Ink & Switch, Yjs, Automerge): Combined CRDTs with IndexedDB/SQLite-Wasm to bring sub-frame responsiveness to collaborative web apps.
Production Pitfalls
- Unbounded tombstone growth: Deleted characters in sequence CRDTs stay as invisible tombstones so concurrent edits know where they sat; without snapshot compaction, a 10 KB note can bloat to 50 MB of history.
- Wall-clock
Date.now()tie-breakers: Relying on a user's system clock for Last-Write-Wins lets a laptop with a clock set to 2099 win every merge forever.
- When not to use CRDTs: For strict financial ledgers, inventory counts, or unique-username claims where two offline writes cannot both succeed, use server-authoritative transactions instead.
Connections & Logical Next Steps
Replicated operation logs require deterministic command application to converge across offline clients.
Offline-capable local-first apps pair IndexedDB persistence with a Service Worker shell.
Optimistic UI rolls back if the server rejects; Local-First treats local storage as primary and merges via CRDTs.
IndexedDB persists single-device B-tree records, whereas CRDTs merge concurrent multi-device edits deterministically.
Seen in Architecture Autopsies
Mechanical Comparisons
IndexedDB persists single-device B-tree records, whereas CRDTs merge concurrent multi-device edits deterministically.
Optimistic UI rolls back if the server rejects; Local-First treats local storage as primary and merges via CRDTs.