yjs-best-practices

Yjs Best Practices

Comprehensive guide for implementing real-time collaborative applications with Yjs — the high-performance CRDT framework. Contains 24 rules across 8 categories covering document lifecycle, shared types, providers, editor bindings, awareness, undo/redo, common pitfalls, and debugging.

When to Apply

Reference these guidelines when:

• Creating or managing Y.Doc instances for collaborative documents
• Using shared types (Y.Text, Y.Array, Y.Map, Y.XmlFragment) for synced data
• Setting up network providers (y-websocket, y-webrtc) or persistence (y-indexeddb)
• Integrating Yjs with editors (TipTap, ProseMirror, CodeMirror, Quill, Monaco)
• Implementing user presence and cursor awareness
• Adding undo/redo to collaborative editing
• Debugging sync issues, state vector mismatches, or update encoding

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Core Document Lifecycle	CRITICAL	core-
2	Shared Types	HIGH	types-
3	Providers	HIGH	provider-
4	Editor Bindings	HIGH	binding-
5	Awareness	MEDIUM	awareness-
6	Undo / Redo	MEDIUM	undo-
7	Pitfalls	MEDIUM	pitfall-
8	Debugging	LOW-MEDIUM	debug-

Quick Reference

Core (CRITICAL)

• core-ydoc-setup — Y.Doc creation, clientID, gc setting
• core-transactions — transact() bundling, origin parameter, event ordering
• core-document-updates — encodeStateAsUpdate, applyUpdate, mergeUpdates, state vectors
• core-garbage-collection — gc flag, when to disable for version history

Shared Types (HIGH)

• types-ytext — Text & RichText, insert/format/delta, Quill compatibility
• types-yarray — Ordered sequences, insert/delete/push, nested types
• types-ymap — Key-value storage, observe, historical key retention gotcha
• types-ymap-ykeyvalue — YKeyValue from y-utility for efficient key-value (524KB → 271B)
• types-xml — Y.XmlFragment/Element/Text for structured documents

Providers (HIGH)

• provider-websocket — y-websocket client and server setup
• provider-webrtc — y-webrtc peer-to-peer connections
• provider-indexeddb — y-indexeddb offline persistence
• provider-custom — Building custom providers, update properties

Editor Bindings (HIGH)

• binding-tiptap — y-prosemirror with TipTap
• binding-prosemirror — y-prosemirror directly; .ProseMirror-yjs-cursor styling, shared schema
• binding-codemirror — y-codemirror.next
• binding-quill — y-quill; register quill-cursors before new Quill()
• binding-monaco — y-monaco; .yRemoteSelection* cursor CSS, SSR, dedupe

Awareness (MEDIUM)

• awareness-protocol — Presence, cursors, setLocalStateField

Undo/Redo (MEDIUM)

• undo-manager — Y.UndoManager, captureTimeout, trackedOrigins, cursor restoration

Pitfalls (MEDIUM)

• pitfall-duplicate-imports — CJS/ESM double-import breaks sync; also dedupe y-protocols, bindings, and editor packages
• pitfall-subdocuments — When to use vs Y.Map alternatives
• pitfall-v2-encoding — useV2Encoding experimental flag

Debugging (LOW-MEDIUM)

• debug-common-issues — logUpdate, state inspection, connection debugging

How to Use

Read individual rule files for detailed explanations and code examples:

rules/core/core-ydoc-setup.md
rules/shared-types/types-ytext.md
rules/providers/provider-websocket.md

Each rule file contains:

• Brief explanation of why it matters
• Correct code example with explanation
• Verification checklist
• Source pointers to official docs

Compiled Documents

• AGENTS.md — Compressed index of all rules with file paths (start here)
• AGENTS.full.md — Full verbose guide with all rules expanded inline