loro-dev/loro

Loro

Use this skill to help users build applications with Loro. Start from the user's product goal, then choose the narrowest chapter that answers it. Load a second chapter only when the task crosses domains.

Select A Chapter

• Read references/topic-map.md if the task is broad and you need to route it.
• Read references/fit-and-architecture.md for product fit, installation, language/package choices, first examples, and core mental models.
• Read references/containers-and-encoding.md for choosing containers, shaping documents, exporting updates, snapshots, persistence, shallow snapshots, and redaction.
• Read references/sync-versioning-and-events.md for realtime/offline sync, version vectors, frontiers, checkout, undo, presence, timestamps, events, and Inspector.
• Read references/richtext-and-editors.md for LoroText, cursors, applyDelta, updateByLine, loro-prosemirror, Tiptap, and CodeMirror.
• Read references/mirror-and-react.md for loro-mirror, $cid, idSelector, validation, selectors, and React integration.
• Read references/performance-and-tradeoffs.md for scaling, document/update size, loading speed, and workload tradeoffs.

Route Common Tasks

• “I am new to Loro / should I use it / show me a first example”
  • Start with fit-and-architecture.md
• “Which language package or binding should I use?”
  • Start with fit-and-architecture.md
• “Build a collaborative document model / choose data types / persist history”
  • Start with containers-and-encoding.md
  • Add sync-versioning-and-events.md if version/history behavior matters
• “Sync devices, store data, use snapshots, time travel, undo, or presence”
  • Start with sync-versioning-and-events.md
• “Integrate ProseMirror, Tiptap, CodeMirror, or custom rich text”
  • Start with richtext-and-editors.md
  • Add sync-versioning-and-events.md if undo/version/event behavior matters
• “Model app state with loro-mirror or loro-mirror-react”
  • Start with mirror-and-react.md
  • Add containers-and-encoding.md if schema semantics depend on container choice
• “Explain performance, large documents, loading, update size, or tradeoffs”
  • Start with performance-and-tradeoffs.md
• “Decide whether Loro is the right tool”
  • Start with fit-and-architecture.md
  • Add performance-and-tradeoffs.md if workload scale matters

Execute The Task

1. Classify the task before reading everything.
2. Load one primary chapter.
3. Load at most one secondary chapter for cross-domain work.
4. Keep solutions grounded in Loro semantics:
   • choose data types by merge behavior,
   • distinguish state version from history version,
   • keep ephemeral state out of persisted CRDT data,
   • use stable cursors for collaborative selections,
   • design sync around updates and snapshots rather than a central locking protocol.

Keep Guardrails

• Do not assume CRDTs are the right fit for hard invariants, exclusivity, or authorization-at-write-time problems.
• Do not model editable text as plain strings when user intent requires merged edits.
• Do not reuse peer IDs across concurrent sessions.
• Do not confuse detached documents with detached containers.
• Do not persist cursor presence, hover state, or connection state inside the main document; use ephemeral state.