CRDTs and Local-First Sync: Picking a Model Without the Academic Fog

Local-first software promises a seductive experience: your data lives on your device, edits feel instant, and sync happens in the background without turning every keystroke into a network round trip. Conflict-free replicated data types (CRDTs) are often part of that story—they are mathematical structures designed so independent edits can merge without a central referee waving a flag every time two people type at once.

They are also easy to misunderstand. “Conflict-free” does not mean “free from surprises,” and CRDTs are not a drop-in substitute for product decisions about permissions, deletion, and meaning. This article separates the useful intuition from the academic fog so you can evaluate libraries and architectures without drowning in papers.

We will walk through the core guarantee, the product boundaries around it, transport and security realities, and the places teams stumble—deletion, permissions, and storage. By the end, you should know whether to keep reading papers or whether a simpler sync strategy matches your actual requirements.

What problem CRDTs actually solve

Traditional replication often assumes a single source of truth and a clear ordering of events. That works until you go offline, or until two devices edit independently and both come back online expecting to win. CRDTs tackle a narrower question: can we define update rules so that, no matter what order messages arrive, every replica ends up in the same state?

If the answer is yes for your data model, you gain a powerful property: you can apply local updates immediately and reconcile later without locking the user behind a spinner. If the answer is no—or if your product semantics cannot be expressed in merge-friendly updates—you still need human conflict resolution or explicit locking.

Events, ops, and the mental model

Most developer-facing explanations talk about “operations” that commute or converge. In practice, you will spend time choosing identifiers, deciding how to represent moves versus deletes, and defining what “the same” means when two users edit the same paragraph. The math guarantees convergence given a compatible data type; the product still defines what convergence should feel like.

That distinction matters when you evaluate libraries. A CRDT implementation can be correct and still produce a bad user experience if your model does not match how people think about the document. Correctness is not the same thing as kindness.

Local-first is a product stance, not a library feature

Shipping local-first means you accept responsibility for storage, migrations, encryption, backup, and multi-device behavior. CRDTs can help with merge semantics, but they do not magically solve GDPR export, account deletion, or “what happens when a user edits a row they no longer have permission to see.”

Think of CRDTs as one tool in a larger box: persistence, networking, auth, and UX must align. A beautiful merge algorithm is cold comfort if your app cannot recover from a corrupted local store or explain to a user why two edits produced a result they did not expect.

Where CRDTs shine in practice

They tend to work well when the data model is additive or structured so concurrent edits compose cleanly. Collaborative text with character-wise identities, shared counters, and certain graph-like updates are common examples. The implementations are mature enough that many teams rely on libraries rather than inventing their own from scratch.

They also shine when latency is unreliable. If your users are on planes, factory floors, or spotty LTE, optimistic local merges feel more humane than “save failed, try again.”

Pairing CRDTs with transport layers

Replication still needs a pipe: WebSockets, MQTT, peer-to-peer sync, or a simple file drop. CRDTs handle merge semantics; they do not replace authentication, authorization, or replay protection. If an attacker can inject bogus operations, your merge rules will faithfully converge—toward the wrong world. Treat the transport as a security boundary, not a friendly neighbor.

Backpressure and batching matter too. High-frequency edits can flood a network if you naively ship every micro-operation. Debouncing, batching, and differential sync are engineering concerns that sit beside the CRDT layer.

Where CRDTs frustrate teams

Deletion and tombstones are a classic pain point. Removing a thing from a shared world is not always the inverse of adding it; you may need tombstones, metadata, or policy rules to prevent “zombie” data from resurrecting. If your product cannot explain why a deleted note reappeared briefly, users will blame you—not the math.

Compression and storage costs matter. CRDTs can carry metadata overhead to preserve identity and ordering. For large documents or high-frequency edits, you need compaction strategies and an understanding of what history you must retain.

Human meaning is still ambiguous. Two people editing “the title” might produce a merged string that is technically valid but editorially nonsense. CRDTs resolve state, not taste.

Permissions and partial visibility

Real products rarely give every participant identical views. Comment threads, redacted fields, and workspace boundaries add rules that pure structure may not encode. If you replicate operations that should not be visible to a device, you leak secrets; if you filter them out, you must ensure merges still converge for authorized participants. This is where “local-first” meets policy engines, not just data structures.

Picking a model without reading a thesis

Start from user stories, not from algorithms. Ask: “What is the smallest unit of edit?” “What must never fork?” “What must always be undoable?” Then map those answers to merge rules. If you cannot describe the behavior in plain language, your users will not understand it either.

Prototype with realistic chaos: offline edits, delayed packets, and clock skew. CRDTs are not supposed to depend on perfect clocks, but your surrounding systems might still assume time ordering for logging or analytics. Keep those concerns separate.

Evaluation checklist for teams

• Write a “merge story” doc. Three short scenarios with expected outcomes, including at least one deletion and one permission change.
• Measure storage growth. Record document size after heavy editing sessions; project a year of use.
• Test crash recovery. Kill the app mid-merge, reboot offline, and come back online.
• Plan observability. You need operation IDs in logs to debug surprising merges.

Operational concerns that dominate shipping

Schema evolution. Local data outlives deploys. Plan migrations carefully, including downgrade paths if your app rolls back.

Security. End-to-end encryption and CRDTs can coexist, but key rotation and multi-device access add complexity. You cannot bolt security on as an afterthought.

Testing. Property-based tests help catch merge edge cases. Manual QA alone will miss combinations.

Support. If merges surprise users, you need tooling to inspect history and explain outcomes.

Finally, budget time for education. Local-first apps change user expectations about backups, multi-device sign-in, and what “synced” means. If marketing promises instant magic, support will pay for it—CRDTs cannot negotiate with angry humans.

When not to reach for CRDTs

If your system is truly centralized, strongly consistent, and always online, simpler patterns may suffice. If conflicts are rare and business rules require human judgment, you might prefer explicit conflict screens over automatic merges that hide intent.

Similarly, if your data is fundamentally relational with strict invariants, you may spend more time bending CRDTs than you would building a pragmatic sync layer with occasional locks.

Operational transformation vs CRDTs: the sibling debate

Operational transformation (OT) powers many classic collaborative editors with a central server ordering operations. It can produce excellent UX when online, but it assumes a reliable coordinator for ordering. CRDTs push merge logic into the data structure so peers can progress independently. Neither is universally better; they optimize for different availability assumptions. Hybrid systems exist, but they add complexity—know why you need the hybrid before you build it.

Migrating from a traditional app

If you already have a Postgres-shaped world, moving to local-first CRDT-backed storage is not a weekend migration. Plan for dual-write periods, reconciliation jobs, and user-visible cutovers. Expect to model “last writer wins” habits out of your team’s vocabulary slowly. Data migration scripts are only half the battle; UX copy and undo behavior must also change.

Skills your team needs

Beyond TypeScript fluency, you want comfort with distributed systems debugging: partial failures, duplicate delivery, and idempotency. A frontend engineer and a backend engineer who can read each other’s traces will outperform a solo genius with a perfect algorithm.

Closing take

CRDTs are a powerful idea for local-first collaboration, but they are not a magic wand. They buy you mathematically consistent merges at the cost of modeling discipline and operational complexity. Pick them when your product genuinely needs offline-first, concurrent editing, and merge semantics that you can explain to a tired user. Otherwise, keep the architecture simpler—and your future self will thank you.

If you remember only one thing, let it be this: convergence is a property of your data model and your rules, not a sticker you slap on after the fact. Start from behavior you can defend in a support ticket. The math can be elegant later; empathy for confused users has to be there from day one.