diff --git a/pages/_meta.js b/pages/_meta.js index b201cdc..9a32420 100644 --- a/pages/_meta.js +++ b/pages/_meta.js @@ -13,6 +13,10 @@ export default { title: "Docs", type: "page" }, + kb: { + title: "Knowledge Base", + type: "page" + }, blog: { title: "Blog", type: "page" diff --git a/pages/kb/_meta.js b/pages/kb/_meta.js new file mode 100644 index 0000000..98c079d --- /dev/null +++ b/pages/kb/_meta.js @@ -0,0 +1,10 @@ +export default { + index: { + title: "Knowledge Base" + }, + "what-is-crdt": "What Is a CRDT?", + "loro-vs-yjs": "Loro vs Yjs", + "crdt-library-comparison": "CRDT Library Comparison", + "build-collaborative-editor": "Build a Collaborative Editor", + "crdt-time-travel": "CRDT Time Travel" +} diff --git a/pages/kb/build-collaborative-editor.mdx b/pages/kb/build-collaborative-editor.mdx new file mode 100644 index 0000000..821ccf2 --- /dev/null +++ b/pages/kb/build-collaborative-editor.mdx @@ -0,0 +1,91 @@ +--- +title: "How to Build a Collaborative Editor with CRDTs" +description: "Learn the key architecture decisions behind building a collaborative editor, including document model, sync, offline support, conflict resolution, and version history." +keywords: "build collaborative editor, collaborative text editor architecture, real-time editor crdt, collaborative editing tutorial" +--- + +# How to Build a Collaborative Editor with CRDTs + +Building a collaborative editor is not just about broadcasting keystrokes. A real product has to survive concurrent edits, reconnect after network loss, preserve document structure, and help users recover from mistakes. + +CRDTs are often a strong fit because they let each client update locally and synchronize later while still converging on the same document state. + +## What a collaborative editor actually needs + +At minimum, you need: + +- a document model for the shared content +- a sync layer to move updates between clients +- a persistence layer so state survives app restarts and reconnects +- presence / awareness for cursors, selections, and who is online +- a history model for undo, restore, and version inspection +- auth and permissions so not everyone can mutate everything + +## Why CRDTs are a good fit + +CRDTs help with the core document-state problem: + +- multiple users edit concurrently +- clients may be offline temporarily +- updates can arrive in different orders +- all replicas still need to converge + +## What CRDTs solve — and what they do not + +CRDTs help with shared document state, concurrent merge behavior, offline edits that sync later, and deterministic convergence. + +They do **not** automatically solve authentication, authorization, presence, transport infrastructure, or product-specific permission flows. + +## The core architecture pieces + +A practical collaborative editor usually has these parts: + +1. Document model +2. Local editing state +3. Sync transport +4. Persistence +5. Presence / awareness +6. Version history + +## Text editors vs structured editors + +There is a big difference between a shared text buffer and a structured collaborative editor. If the product is trending toward structured content, pick a library that will not fight you later. + +## Offline-first and reconnect behavior + +A solid collaborative editor should handle: + +- local edits while disconnected +- replaying updates on reconnect +- merging with remote edits safely +- reloading large documents without bizarre corruption or duplicate state + +## Why version history matters + +If you stop at convergence, you get a collaborative system. +If you add inspectable history and restore points, you start getting a trustworthy product. + +## A practical stack with Loro + +A simple architecture with Loro might look like this: + +- client: editor UI + Loro document in memory +- transport: WebSocket, WebRTC, or your own sync channel +- backend: stores snapshots and/or updates, enforces auth and permissions +- history UX: built on top of Loro's document history / time-travel capabilities + +## Common mistakes when building collaborative editors + +- treating presence like document state +- only testing on perfect networks +- forgetting recovery and versioning +- choosing a data model that is too shallow + +## What to read next + +- [Get Started with Loro](/docs/tutorial/get_started) +- [Learn how sync works](/docs/tutorial/sync) +- [Explore Time Travel](/docs/tutorial/time_travel) +- [Understand the CRDT basics](/kb/what-is-crdt) +- [Loro vs Yjs](/kb/loro-vs-yjs) +- [CRDT Library Comparison](/kb/crdt-library-comparison) diff --git a/pages/kb/crdt-library-comparison.mdx b/pages/kb/crdt-library-comparison.mdx new file mode 100644 index 0000000..0fc9624 --- /dev/null +++ b/pages/kb/crdt-library-comparison.mdx @@ -0,0 +1,92 @@ +--- +title: "CRDT Library Comparison: Loro vs Yjs vs Automerge" +description: "A practical comparison of CRDT libraries including Loro, Yjs, and Automerge across ecosystem, language support, data models, local-first fit, and collaboration use cases." +keywords: "crdt library comparison, best crdt library, yjs vs automerge vs loro, javascript crdt library" +--- + +# CRDT Library Comparison + +There is no single best CRDT library for every product. Real teams choose one for a specific product shape: a collaborative editor, a local-first document app, a structured knowledge tool, or a shared data layer with offline sync. + +## Quick answer + +Choose **Yjs** if ecosystem safety and editor integration depth matter most. + +Choose **Automerge** if you are strongly local-first in philosophy and your use case leans toward general replicated app state. + +Choose **Loro** if you want collaboration plus a stronger document history/time-travel story, especially for structured content. + +## What to compare when choosing a CRDT library + +Useful criteria: + +- document model shape +- ecosystem maturity +- local-first fit +- history / versioning story +- long-term product fit vs fastest adoption + +## Comparison overview + +### Yjs + +Strong JavaScript adoption, collaborative editor mindshare, mature ecosystem. + +### Automerge + +Strong local-first association and replicated app-state narrative. + +### Loro + +Richer structured document orientation, stronger emphasis on document history and time travel. + +## Comparison table + +| Dimension | Loro | Yjs | Automerge | +| --- | --- | --- | --- | +| Ecosystem maturity | Growing | Strongest today | Established but more niche in some workflows | +| JavaScript mindshare | Moderate | Strong | Moderate | +| Editor ecosystem gravity | Limited vs Yjs | Strongest | Lower than Yjs | +| Structured document fit | Strong | Good | Good | +| History / time-travel emphasis | Strong | Varies by surrounding architecture | Strong local-first narrative | + +**TODO:** Replace directional wording with tighter, citation-backed capability statements where official docs give enough evidence. + +## Best for JavaScript-first teams + +Yjs has the clearest advantage today if you want the most familiar collaboration ecosystem. + +## Best for local-first products + +All three libraries can participate in local-first architectures, but they support different product stories. + +## Best for document history and time travel + +This is where Loro stands out most clearly. + +## Best for editor integrations + +If your main question is which library gives the broadest editor-oriented ecosystem and least surprising integration path, Yjs is usually the strongest answer. + +## Where Loro is differentiated + +Loro becomes more compelling when: + +- the document is highly structured +- tree-like or movable content matters +- version history is user-facing +- collaboration and restore/replay belong in the same product story + +## Common mistakes when choosing a CRDT library + +- picking on popularity alone +- over-focusing on toy benchmarks +- ignoring history until later +- treating all collaborative apps as text editors + +## What to read next + +- [What Is a CRDT?](/kb/what-is-crdt) +- [Loro vs Yjs](/kb/loro-vs-yjs) +- [How to Build a Collaborative Editor](/kb/build-collaborative-editor) +- [Get Started with Loro](/docs/tutorial/get_started) diff --git a/pages/kb/crdt-time-travel.mdx b/pages/kb/crdt-time-travel.mdx new file mode 100644 index 0000000..beac1a8 --- /dev/null +++ b/pages/kb/crdt-time-travel.mdx @@ -0,0 +1,64 @@ +--- +title: "CRDT Time Travel: Version History for Local-First and Collaborative Apps" +description: "See how CRDT time travel enables version history, undoable exploration, and Git-like document inspection in collaborative and local-first applications." +keywords: "crdt time travel, document version history crdt, local-first version control, collaborative editing history" +--- + +# CRDT Time Travel + +Most collaboration content focuses on one thing: how multiple replicas converge. But real products also need to answer what changed, whether users can restore an older version, and how a document evolved over time. + +In a CRDT system, time travel means you can work with more than just the latest state. You can inspect history, reconstruct earlier versions, and build product features around document evolution. + +## What does “time travel” mean in a CRDT system? + +Time travel usually means some combination of: + +- viewing earlier document states +- restoring a previous version +- replaying changes over time +- inspecting how a document evolved +- building history-aware product features on top of synchronized state + +## Why version history matters in collaborative apps + +Version history helps with: + +- recovery +- trust +- review and inspection +- product differentiation + +## Why this is hard to bolt on later + +Once persistence model, sync flow, and product assumptions revolve around only the latest state, adding high-quality version history becomes much more painful. + +## CRDT time travel vs undo/redo + +Undo is often local and session-oriented. +Time travel is about durable document history. + +## Product features enabled by time travel + +- version history views +- restore flows +- replay / change walkthroughs +- snapshot-based workflows +- trust-building UX + +## How Loro fits here + +Loro is not only positioned as a CRDT library for convergence. It also has a stronger story around document history and time travel. + +**TODO:** Align exact terminology and capability wording with Loro’s official time-travel docs so the page stays precise instead of vague. + +## When you should care about this feature + +Care early if your product needs restore, review, recoverability, or structured content history as part of the UX. + +## What to read next + +- [Time Travel Tutorial](/docs/tutorial/time_travel) +- [Learn how sync works](/docs/tutorial/sync) +- [Loro vs Yjs](/kb/loro-vs-yjs) +- [How to Build a Collaborative Editor](/kb/build-collaborative-editor) diff --git a/pages/kb/index.mdx b/pages/kb/index.mdx new file mode 100644 index 0000000..760df1e --- /dev/null +++ b/pages/kb/index.mdx @@ -0,0 +1,46 @@ +--- +title: "Loro Knowledge Base" +description: "Search-first guides for CRDTs, collaborative editing, local-first architecture, and evaluating Loro against other CRDT libraries." +keywords: "loro knowledge base, crdt guides, collaborative editing, local-first, yjs alternative" +--- + +import { Cards } from "nextra/components"; + +# Loro Knowledge Base + +Search-first guides for engineers evaluating CRDTs, collaborative editing architecture, and local-first software. + +Use this section when you want the big picture first: +- what CRDTs are +- how to compare Loro with Yjs and Automerge +- how to design a collaborative editor +- why document history and time travel matter + +## Start here + + + + Learn the core idea behind conflict-free replicated data types and why they matter for offline and real-time apps. + + + A practical comparison for teams choosing a CRDT library for collaborative software. + + + Compare Loro, Yjs, and Automerge across ecosystem, data model, and product fit. + + + A search-first architecture guide for collaborative text and document products. + + + Understand document history, replay, and versioning in local-first and collaborative apps. + + + +## Looking for implementation details? + +If you already know what you want to build and just need APIs and examples, go straight to the docs: + +- [Get Started](/docs/tutorial/get_started) +- [CRDT Concepts](/docs/concepts/crdt) +- [Sync Tutorial](/docs/tutorial/sync) +- [Time Travel Tutorial](/docs/tutorial/time_travel) diff --git a/pages/kb/loro-vs-yjs.mdx b/pages/kb/loro-vs-yjs.mdx new file mode 100644 index 0000000..f822e54 --- /dev/null +++ b/pages/kb/loro-vs-yjs.mdx @@ -0,0 +1,87 @@ +--- +title: "Loro vs Yjs: Which CRDT Library Fits Your Collaborative App?" +description: "Compare Loro and Yjs for collaborative editing, local-first apps, performance trade-offs, data model design, and developer ergonomics." +keywords: "loro vs yjs, yjs alternative, best crdt library, collaborative editing crdt" +--- + +# Loro vs Yjs + +If you are choosing a CRDT library for a collaborative app, Yjs is usually the default comparison point. That makes sense: it has a strong ecosystem, broad mindshare, and real adoption in collaborative editors. + +Loro is newer in ecosystem terms, but it is compelling for teams that care about richer document structure, version history, and time travel as product features rather than afterthoughts. + +- choose **Yjs** when ecosystem maturity and existing editor integrations matter most +- choose **Loro** when your product needs stronger document history, richer structured data, and a more explicit local-first + versioning story + +## Quick answer + +Choose **Yjs** if: + +- you want the most established JavaScript collaboration ecosystem +- you already rely on editor bindings built around Yjs +- your team wants the safest community-default choice + +Choose **Loro** if: + +- you want collaboration **and** built-in document history to be first-class +- your app uses more than just flat text +- you care about trees, movable structures, and version-oriented product UX +- you are building a new system rather than migrating a mature Yjs deployment + +## Ecosystem and maturity + +This is where Yjs is clearly stronger today: larger community footprint, broader ecosystem familiarity, more examples and editor integrations. + +## Data model differences + +Loro is especially interesting when your document model includes: + +- rich text +- maps and lists +- tree-shaped content +- movable containers or structured document state + +## History and time travel + +This is the biggest differentiator. Many collaborative products need version history, restore points, document inspection, and replayable evolution. Loro has a much stronger story around document history and time travel. + +## Performance and architecture + +Performance depends on document size, mutation pattern, history model, and sync workload. + +**TODO:** Add benchmark citations or link to documented performance claims only where publicly supported by Loro/Yjs materials. + +## Developer experience + +Yjs often feels like the familiar ecosystem pick, especially for JavaScript teams already surrounded by editor tooling. + +Loro is attractive when: + +- you want a Rust-first core with JS/WASM usage +- you care about explicit history capabilities +- your app is not just shared text but a structured collaborative document model + +## Who should choose Loro + +Loro is a strong fit if you are: + +- starting a new collaborative product +- building around structured documents, trees, or movable containers +- treating version history as a product feature +- optimizing for local-first architecture rather than only real-time text sync + +## Who should stay with Yjs + +Lean Yjs if: + +- ecosystem depth is your top priority +- your product is already tightly bound to Yjs-specific integrations +- your current architecture works and history/versioning is not a core gap + +## What to read next + +- [Get Started with Loro](/docs/tutorial/get_started) +- [Learn how sync works](/docs/tutorial/sync) +- [See the Time Travel docs](/docs/tutorial/time_travel) +- [CRDT Library Comparison](/kb/crdt-library-comparison) +- [What Is a CRDT?](/kb/what-is-crdt) diff --git a/pages/kb/what-is-crdt.mdx b/pages/kb/what-is-crdt.mdx new file mode 100644 index 0000000..1f15d75 --- /dev/null +++ b/pages/kb/what-is-crdt.mdx @@ -0,0 +1,139 @@ +--- +title: "What Is a CRDT? Conflict-Free Replicated Data Types Explained" +description: "Learn what CRDTs are, how they resolve conflicts in offline and real-time apps, and why they matter for local-first software and collaborative editing." +keywords: "what is crdt, crdt explained, conflict-free replicated data types, local-first crdt, collaborative editing" +--- + +# What Is a CRDT? + +A CRDT (Conflict-Free Replicated Data Type) is a data structure designed for concurrent updates across multiple replicas. In practice, that means two or more users can edit shared state at the same time, sync later, and still end up with the same result. + +If you are building collaborative or local-first software, CRDTs matter because they let clients update state locally instead of waiting for a central lock. That makes offline editing, low-latency interaction, and peer-to-peer or eventually connected sync much easier to support. + +This page explains what CRDTs solve, where they fit, where they do **not** fit, and how Loro uses them in real products. + +## The real problem CRDTs solve + +The core problem is not "how do I send updates over WebSocket." It is what happens when multiple users change the same document while: + +- editing at the same time +- working on unstable networks +- going offline and reconnecting later +- syncing through different servers or peers + +A naive sync model often treats state like a single blob: whoever writes last wins. That sounds simple, but it tends to destroy user intent. + +Imagine one user inserts a paragraph while another user fixes a heading offline. If your sync model is just replacing the latest full document state, one of those edits can disappear. Users do not care that the system was simple internally. They care that their work is gone. + +CRDTs exist to solve exactly this class of problem: concurrent changes to shared state that still need to converge without manual conflict resolution every time. + +## What “conflict-free” means in practice + +The phrase sounds academic, but the practical idea is pretty simple. + +With a CRDT: + +- each replica can accept local updates independently +- replicas can exchange updates later +- the merge result converges to the same state on every replica + +So if Alice edits on her laptop and Bob edits on his tablet, they do not need to take turns through a central lock just to keep the document valid. Their changes can be merged according to the data type's rules. + +"Conflict-free" does **not** mean users never make competing edits. It means the data model is designed so those concurrent edits can be merged deterministically and converge. + +That is the important part: convergence without a fragile pile of custom merge code. + +## A simple CRDT example + +Say two users start from the same text: + +```txt +Hello world +``` + +Now imagine: + +- User A inserts `beautiful ` after `Hello ` +- User B inserts `collaborative ` after `Hello ` + +Both edits happen before sync. + +In a naive system, one update may overwrite the other depending on arrival order. In a CRDT-based text model, both insertions can be preserved, and all replicas will eventually agree on the merged result. + +The exact final order may depend on the CRDT's ordering rules, but the key thing is this: the system converges, and neither edit is silently dropped. + +## CRDT vs OT vs naive sync + +A lot of people first hear about CRDTs while comparing them to OT (Operational Transformation). Fair enough — both are used in collaborative systems, especially editors. + +### Naive sync + +Naive sync usually means one of these: + +- full-state replacement +- last-write-wins for fields +- app-specific merge logic glued together later + +This can be fine for simple forms or settings screens, but it falls apart fast when users are editing structured shared content concurrently. + +### OT + +OT is well-known from collaborative document editors. It transforms operations against each other so changes can still apply in the right order. + +OT can work very well, but it often depends more heavily on central coordination and carefully maintained transformation logic. For some products, that is a good trade. For others — especially offline-first or multi-topology sync — it gets messy. + +### CRDT + +CRDTs push more of the concurrency handling into the data type design itself. Instead of relying on a central authority to serialize everything, the replicated state and update rules are built to converge. + +That makes CRDTs especially attractive when you care about: + +- local-first interaction +- intermittent connectivity +- peer-to-peer or flexible sync topologies +- preserving concurrent user intent + +## Common CRDT data types + +Common examples include text, list, map, and tree. + +This is where product reality matters. Many apps are not just shared text. They are shared structured content. If your state model includes movable blocks, nested nodes, or rich content trees, the shape of the CRDT data model matters a lot. + +## Where CRDTs are a good fit + +Typical examples: + +- collaborative text editors +- local-first note apps +- design tools and whiteboards +- knowledge bases with shared structure +- task or workflow apps with nested content +- multiplayer interfaces with structured shared state + +## Where CRDTs are not a great fit + +CRDTs may be overkill when: + +- your data is mostly CRUD forms with low concurrency +- you already have a strongly centralized workflow that users accept +- your state has simple overwrite semantics and no collaboration pressure +- storage and metadata overhead matters more than concurrent merge quality + +## Why CRDTs matter for local-first software + +A local-first app treats the local device as a primary place where work happens, not just a cache for server state. CRDTs support that model by letting local changes happen first and synchronize later. + +## How Loro fits in + +Loro is a CRDT library built for collaborative and local-first software. It gives you a shared document model that can merge concurrent changes while supporting rich data structures like text, lists, maps, and trees. + +What makes Loro especially interesting is that it is not only about convergence. It also has a stronger story around document history and time travel. + +## What to read next + +- [CRDT Concepts](/docs/concepts/crdt) +- [Get Started with Loro](/docs/tutorial/get_started) +- [Learn how sync works](/docs/tutorial/sync) +- [See why time travel matters](/docs/tutorial/time_travel) +- [Loro vs Yjs](/kb/loro-vs-yjs) +- [CRDT Library Comparison](/kb/crdt-library-comparison)