velt-crdt-best-practices（velt crdt 最佳实践）

Velt CRDT Best Practices

Comprehensive best practices guide for implementing real-time collaborative editing with Velt CRDT (Yjs), maintained by Velt. Contains 38 rules across 5 categories, prioritized by impact to guide automated code generation and debugging.

When to Apply

Reference these guidelines when:

• Setting up Velt client and CRDT stores
• Integrating with Tiptap, BlockNote, CodeMirror, or ReactFlow
• Implementing real-time synchronization
• Managing version history and checkpoints
• Debugging collaboration or sync issues
• Testing multi-user collaboration

Rule Categories by Priority

Quick Reference

1. Core CRDT (CRITICAL)

• core-install - Install correct CRDT packages for your framework
• core-velt-init - Initialize Velt client before creating stores
• core-store-create-react - Use useVeltCrdtStore hook for React
• core-store-create-vanilla - Use createVeltStore for non-React
• core-store-types - Choose correct store type (text/array/map/xml)
• core-store-subscribe - Subscribe to store changes for remote updates
• core-store-update - Use update() method to modify values
• core-version-save - Save named version checkpoints
• core-encryption - Use custom encryption provider for sensitive data
• core-webhooks - Use webhooks to listen for CRDT data changes
• core-rest-api - Use REST API to retrieve CRDT data server-side
• core-activity-debounce - Use setActivityDebounceTime() to control how frequently batched CRDT editor activities are flushed
• core-activity-action-types - Use CrdtActivityActionTypes constant for type-safe CRDT activity filtering instead of raw strings
• core-message-stream - Use CrdtElement message-stream methods (pushMessage, onMessage, getMessages, getSnapshot, saveSnapshot, pruneMessages) for Yjs-backed collaborative editors
• core-debug-storemap - Use VeltCrdtStoreMap for runtime debugging
• core-debug-testing - Test with multiple browser profiles

2. Tiptap Integration (CRITICAL)

• tiptap-install - Install Tiptap CRDT packages
• tiptap-setup-react - Use useVeltTiptapCrdtExtension for React
• tiptap-setup-vanilla - Use createVeltTipTapStore for non-React
• tiptap-disable-history - Disable Tiptap history to prevent conflicts
• tiptap-editor-id - Use unique editorId per instance
• tiptap-cursor-css - Add CSS for collaboration cursors
• tiptap-testing - Test collaboration with multiple users

3. BlockNote Integration (HIGH)

• blocknote-install - Install BlockNote CRDT package
• blocknote-setup-react - Use useVeltBlockNoteCrdtExtension
• blocknote-editor-id - Use unique editorId per instance
• blocknote-testing - Test collaboration with multiple users

4. CodeMirror Integration (HIGH)

• codemirror-install - Install CodeMirror CRDT packages
• codemirror-setup-react - Use useVeltCodeMirrorCrdtExtension for React
• codemirror-setup-vanilla - Use createVeltCodeMirrorStore for non-React
• codemirror-ycollab - Wire yCollab extension with store's Yjs objects
• codemirror-editor-id - Use unique editorId per instance
• codemirror-testing - Test collaboration with multiple users

5. ReactFlow Integration (HIGH)

• reactflow-install - Install ReactFlow CRDT package
• reactflow-setup-react - Use useVeltReactFlowCrdtExtension
• reactflow-handlers - Use CRDT handlers for node/edge changes
• reactflow-editor-id - Use unique editorId per instance
• reactflow-testing - Test collaboration with multiple users

How to Use

Read individual rule files for detailed explanations and code examples:

rules/shared/core/core-install.md
rules/shared/tiptap/tiptap-disable-history.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Verification checklist
• Source pointer to Velt documentation

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