Local-First Apps: CRDTs, Sync Engines, and Conflict Resolution That Works

Most applications treat the cloud as the primary source of truth. Every read goes to a server, every write waits for a round trip, and every offline moment becomes a degraded experience. That model worked when networks were reliable and devices were thin clients. It breaks down on flaky mobile networks, in field work, on planes, in hospitals, and in any product where users expect instant response. Local-first software flips the default: the device holds the primary copy, the UI reads and writes locally, and synchronization happens in the background.

Going local-first is not just adding an offline cache. It changes the data model, the sync protocol, the conflict resolution strategy, and the security model. This article explains the architecture, the algorithms, and the practical trade-offs behind local-first apps that actually work.

What Local-First Actually Means

Local-first is a set of principles, not a single technology. The most useful definition includes five properties:

• Primary copy on device: The user’s device stores the authoritative working copy. The server is a sync relay, backup, and collaboration hub, not a gatekeeper for every operation.
• Offline by default: The app remains fully usable without a network connection. Reads and writes complete immediately and sync later.
• Sync as a background process: The sync engine reconciles changes across devices and users without blocking the UI.
• User ownership and privacy: Data can be exported, encrypted, and stored where the user chooses. The backend does not need plaintext access to everything.
• Eventual consistency with clear semantics: Replicas converge, and the application defines how conflicts are resolved rather than hoping they never happen.

This is different from a traditional offline-first cache. A cache is disposable and server-authoritative. A local-first store is durable and peer-aware. If the server disappears, the app still works. If two devices edit the same record, the system has a defined merge path.

Why Now? The Forces Behind Local-First

Several trends make local-first practical today:

• Powerful clients: Phones, laptops, and browsers have enough CPU, memory, and storage to run CRDTs, indexes, and encryption locally.
• Better sync primitives: Libraries like Automerge, Yjs, and ElectricSQL have matured, and WebSockets, WebRTC, and HTTP/3 make transport easier.
• Privacy expectations: Regulations like GDPR and CCPA push teams to minimize server-side plaintext and support data export.
• Collaboration demand: Users expect Google Docs-style real-time collaboration and offline editing in the same product.
• Edge and mobile reality: Networks are fast but not always available. Latency and packet loss are normal, not exceptional.

The result is a shift from server-centric CRUD to replicated data structures and sync engines.

The Core Architecture of a Local-First System

A local-first app has five major layers. You can implement them with different tools, but the responsibilities stay the same.

1. Local Store

The local store is the app’s source of truth during normal use. It should support fast reads, transactional writes, and durable persistence. Options include SQLite, IndexedDB, Realm, and embedded key-value stores. The store must also keep enough metadata to support sync: operation IDs, timestamps, version vectors, and tombstones.

2. Operation Log

Instead of syncing final state, many local-first systems sync operations or changes. An operation is a small, immutable description of user intent: create a task, set a field, delete a row, move an item. The log provides a natural audit trail and makes idempotent replay possible. Not every system needs a full event-sourcing log, but some form of change tracking is essential.

3. Sync Engine

The sync engine compares local and remote versions, exchanges missing operations, and applies merges. It handles retries, backoff, ordering, and deduplication. A good sync engine is incremental: it sends only what changed since the last known state. It also supports anti-entropy, a periodic process that detects and repairs divergence between replicas.

4. Transport and Anti-Entropy

Transport can be WebSockets, HTTP long polling, WebRTC data channels, or even sneaker-net file exchange. The key requirement is that sync is unreliable and out-of-order by default. Anti-entropy protocols such as Merkle trees, version vectors, and hash comparisons help replicas find missing data without exchanging entire datasets.

5. Conflict Resolution Layer

This is where local-first gets interesting. When two replicas edit the same data without coordination, the system must merge them. The merge can be automatic, semantic, or human-in-the-loop. The choice depends on the data type and the cost of a wrong merge.

Conflict Resolution: OT, CRDTs, and Beyond

There are two classic approaches to collaborative editing and replicated data: Operational Transformation (OT) and Conflict-Free Replicated Data Types (CRDTs). Modern local-first systems often use CRDTs because they work well in peer-to-peer and offline settings.

Operational Transformation (OT)

OT was popularized by Google Docs. It transforms concurrent operations so they can be applied in different orders and still converge. OT requires a central server to order operations and transform them, which makes offline and peer-to-peer collaboration harder. It is efficient for text and mature, but it is not the easiest fit for local-first architectures that need to work without a central authority.

Conflict-Free Replicated Data Types (CRDTs)

CRDTs are data structures that can be replicated across multiple nodes, updated independently, and merged deterministically. They guarantee strong eventual consistency: if all replicas receive all updates, they converge to the same state. CRDTs come in two main flavors:

• State-based CRDTs: Replicas exchange full or partial states and merge them with a join operation. They are simple to reason about but can be expensive to transmit.
• Operation-based CRDTs: Replicas exchange operations. They require reliable causal delivery but usually send less data.

Common CRDTs include:

• LWW Register: Last-Writer-Wins. The value with the highest timestamp wins. Simple, but it can silently discard concurrent edits.
• G-Counter and PN-Counter: Grow-only and positive-negative counters. Each replica increments its own slot, and the merge takes the maximum per slot. The value is the sum.
• OR-Set: Observed-Remove Set. Elements can be added and removed without losing concurrent additions. Each addition has a unique tag, and removal marks known tags as removed.
• Sequence CRDTs: Structures like RGA, YATA, and Logoot manage ordered lists and text. They assign stable positions to elements so concurrent insertions can be merged without breaking the document.

CRDTs are not magic. They trade coordination for metadata, and that metadata can grow. Compaction, snapshots, and garbage collection are important for long-lived documents.

Hybrid Logical Clocks and Version Vectors

To merge operations, replicas need causality information. Physical clocks are unreliable across devices. Lamport timestamps provide logical ordering, but they do not capture wall-clock time for user-facing LWW decisions. Hybrid Logical Clocks (HLCs) combine physical time with logical counters. Version vectors track which operations each replica has seen. Together, these tools help the sync engine detect missing data and order merges correctly.

A Practical Merge Example

Consider a distributed counter that supports increments and decrements. A PN-Counter can merge without conflicts by keeping per-user counts and taking the maximum for each user’s slot. This avoids double-counting when the same operation is replayed.

type Counter = { increments: Map<UserId, number>, decrements: Map<UserId, number> }

merge(a, b):
  for user in union(a.increments.keys, b.increments.keys):
    increments[user] = max(a.increments[user] or 0, b.increments[user] or 0)
  for user in union(a.decrements.keys, b.decrements.keys):
    decrements[user] = max(a.decrements[user] or 0, b.decrements[user] or 0)
  return { increments, decrements }

value(counter):
  return sum(counter.increments.values) - sum(counter.decrements.values)

This works because each user is the only writer of their own slot. The merge is commutative, associative, and idempotent. Many CRDTs follow the same pattern: partition writes by replica, then combine with a monotonic merge function.

Designing for Sync: Rules That Save You Later

The details of your data model determine whether sync is easy or painful. These rules apply whether you use CRDTs or a custom protocol.

• Model operations, not just state: A row update that overwrites the whole record loses information. Field-level operations preserve concurrent edits.
• Make operations idempotent: Networks duplicate packets. The same operation may arrive twice. Applying it twice should not change the result.
• Use stable, client-generated IDs: Do not depend on auto-increment IDs from a server. Use UUIDs, ULIDs, or content-derived IDs so offline devices can create records safely.
• Keep causality metadata: Version vectors or HLCs help the sync engine know what is missing and what can be safely compacted.
• Design for compaction: Operation logs grow. Snapshots, tombstones, and periodic state compaction keep storage and sync time bounded.
• Define invariants explicitly: Some rules cannot be enforced offline without coordination. Unique usernames, inventory limits, and account balances need a server-side check or a reservation protocol.

Security, Privacy, and Access Control

Local-first can improve privacy because data can stay on the device and sync end-to-end encrypted. But it also creates new challenges.

• End-to-end encryption: Encrypt operations or documents before they leave the device. The server stores ciphertext and cannot read user content. This is powerful but complicates search, moderation, and server-side validation.
• Key management: Users need to recover keys across devices. Use passphrases, hardware keys, or social recovery. Losing a key can mean losing data.
• Metadata leakage: Even with E2EE, the server may see who syncs with whom, when, and how often. Consider metadata minimization and padding if that matters.
• Revocation in offline systems: Removing a collaborator is hard when their device already has a copy. You can rotate keys for future updates, but you cannot unshare past data. Design permissions with this reality in mind.
• Zero trust sync: Treat every sync message as untrusted. Validate signatures, enforce authorization on the server where possible, and avoid trusting client timestamps for security-critical decisions.

Testing and Observability for Local-First Systems

Distributed systems fail in ways that are hard to reproduce. Local-first apps add offline periods, clock skew, and long-lived divergent states. Testing must be systematic.

• Deterministic simulation: Build a simulator that runs many replicas, drops messages, reorders them, and introduces partitions. Deterministic seeds make failures reproducible.
• Property-based testing: Assert invariants such as convergence, idempotence, and commutativity. Generate random operation sequences and verify that all replicas converge to the same state.
• Network partition tests: Split replicas for minutes or days, make edits on both sides, then reconnect. Verify that merges are correct and that the UI does not block.
• Fuzzing: Feed malformed operations, duplicate messages, and out-of-order updates. The sync engine should reject or ignore invalid data without corrupting state.
• Metrics: Track sync latency, conflict rate, operation log size, compaction time, and failed merges. These metrics reveal whether your data model is fighting the sync engine.

Tools and Frameworks

The local-first ecosystem is growing. Here are common building blocks and where they fit.

• Automerge: A CRDT library for JSON-like documents. It supports rich text, maps, lists, and offline collaboration. Good for document-centric apps.
• Yjs: A high-performance CRDT framework often used for collaborative text and rich text editors. It has bindings for many editors and supports peer-to-peer sync.
• ElectricSQL: Syncs Postgres with local SQLite using a CRDT-inspired model. It aims to make local-first feel like normal SQL.
• Replicache and Rocicorp: A client-side sync framework with mutations, subscriptions, and conflict handling. It focuses on web apps and predictable sync.
• RxDB: A reactive database for JavaScript with replication plugins and offline support. It works with many storage backends.
• PouchDB and CouchDB: A mature sync protocol with revision trees and conflict handling. It works well for offline-first apps but has its own consistency model.
• Firebase and Supabase: Backend platforms with offline persistence and real-time sync. They are convenient but usually server-authoritative, so they are not fully local-first without additional conflict handling.

Choose based on your data model. Document collaboration needs sequence CRDTs. Transactional apps may prefer SQLite plus an operation log. Mobile apps may need a small embedded database with custom sync.

When Not to Go Local-First

Local-first is powerful, but it is not always the right choice.

• Strong global invariants: Banking balances, inventory reservations, and unique usernames often require a central authority. You can still use local-first UX with server-side reservations, but pure offline writes may need rejection or compensation.
• Very high conflict domains: If users constantly edit the same fields, CRDT metadata and merge complexity grow. Sometimes a central lock or a turn-taking workflow is better.
• Huge datasets: Syncing terabytes to every device is impractical. Local-first works best when the working set fits on the device.
• Strict regulatory centralization: Some industries require all data to reside in a controlled server environment. Local-first can still help with caching and UI, but not as the primary source of truth.

An Implementation Roadmap

If you want to adopt local-first without rewriting everything, use an incremental path.

1. Start with read-heavy offline: Cache data locally and make reads instant. This delivers immediate UX value without changing write semantics.
2. Choose a sync model: Decide between operation-based sync, state-based CRDTs, or a hybrid. Match it to your conflict tolerance.
3. Define merge semantics per field: For each important field, specify how conflicts resolve: LWW, multi-value, semantic merge, or manual review.
4. Build a durable outbox: Queue local writes and send them reliably. Handle retries, backoff, and deduplication.
5. Add anti-entropy and snapshots: Periodically compare replicas and compact history. This keeps sync fast and storage bounded.
6. Instrument and simulate: Add metrics and run deterministic simulations before shipping to production.
7. Migrate gradually: Move one feature at a time. Keep a server fallback for features that require strong consistency.

Conclusion

Local-first apps are not just offline apps. They are distributed systems on the client, with all the benefits and responsibilities that come with replication. By choosing the right CRDTs, designing idempotent operations, planning for conflict resolution, and testing under realistic network conditions, you can build software that feels instant, resilient, and respectful of user data. The cloud is still valuable, but it no longer has to be the bottleneck. Start with a clear merge model, keep the sync engine incremental, and let the local copy be the source of truth.