home / skills / velt-js / agent-skills / velt-crdt-best-practices
This skill helps implement real-time collaboration with Velt CRDT by guiding setup, integration, and debugging across editors and stores.
npx playbooks add skill velt-js/agent-skills --skill velt-crdt-best-practicesReview the files below or copy the command above to add this skill to your agents.
---
name: velt-crdt-best-practices
description: Velt CRDT (Yjs) collaborative editing best practices for real-time applications. This skill should be used when implementing collaborative features using Velt CRDT stores, integrating with editors like Tiptap, BlockNote, CodeMirror, or ReactFlow, or debugging sync issues. Triggers on tasks involving real-time collaboration, multiplayer editing, CRDT stores, or Velt SDK integration.
license: MIT
metadata:
author: velt
version: "2.0.0"
---
# Velt CRDT Best Practices
Comprehensive best practices guide for implementing real-time collaborative editing with Velt CRDT (Yjs), maintained by Velt. Contains 35 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
| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Core CRDT | CRITICAL | `core-` |
| 2 | Tiptap Integration | CRITICAL | `tiptap-` |
| 3 | BlockNote Integration | HIGH | `blocknote-` |
| 4 | CodeMirror Integration | HIGH | `codemirror-` |
| 5 | ReactFlow Integration | HIGH | `reactflow-` |
## 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-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
This skill documents Velt CRDT (Yjs) collaborative editing best practices for building reliable real-time applications. It prioritizes 35 concrete rules across core CRDT setup and editor integrations (Tiptap, BlockNote, CodeMirror, ReactFlow). Use it to guide implementation, debugging, and automated code generation for multiplayer editing features.
The skill inspects common setup and integration patterns and highlights critical rules to prevent sync conflicts, data loss, and performance issues. It maps rules by priority, recommends API hooks and store patterns for React and non-React environments, and includes verification checklists and testing guidance. The output helps developers choose correct store types, initialize clients, wire editor extensions, and validate multi-user scenarios.
Do I need different packages for each editor?
Yes. Install the Velt CRDT package tailored to your editor integration (Tiptap, BlockNote, CodeMirror, ReactFlow) to get the appropriate hooks and extensions.
How do I debug state divergence between clients?
Use VeltCrdtStoreMap for runtime inspection, save named version checkpoints, test across multiple browser profiles, and verify subscriptions and update usage.