velt-crdt-best-practices

Files (63)

• AGENTS.full.md
• AGENTS.md
• README.md
• SKILL.md
• metadata.json
• codemirror-setup-vanilla.md · rules/non-react/codemirror/
• core-store-create-vanilla.md · rules/non-react/core/
• tiptap-setup-vanilla.md · rules/non-react/tiptap/
• blocknote-editor-id.md · rules/react/blocknote/
• blocknote-install.md · rules/react/blocknote/
• blocknote-setup-react.md · rules/react/blocknote/
• blocknote-testing.md · rules/react/blocknote/
• codemirror-setup-react.md · rules/react/codemirror/
• core-crdt-utils-hooks.md · rules/react/core/
• core-store-create-react.md · rules/react/core/
• reactflow-editor-id.md · rules/react/reactflow/
• reactflow-handlers.md · rules/react/reactflow/
• reactflow-install.md · rules/react/reactflow/
• reactflow-setup-react.md · rules/react/reactflow/
• reactflow-testing.md · rules/react/reactflow/
• tiptap-nextjs-ssr.md · rules/react/tiptap/
• tiptap-setup-react.md · rules/react/tiptap/
• _sections.md · rules/shared/
• _template.md · rules/shared/
• blocknote-collaboration-manager.md · rules/shared/blocknote/
• blocknote-v1-to-v2-migration.md · rules/shared/blocknote/
• codemirror-collaboration-manager.md · rules/shared/codemirror/
• codemirror-editor-id.md · rules/shared/codemirror/
• codemirror-install.md · rules/shared/codemirror/
• codemirror-testing.md · rules/shared/codemirror/
• codemirror-v1-to-v2-migration.md · rules/shared/codemirror/
• codemirror-ycollab.md · rules/shared/codemirror/
• core-activity-action-types.md · rules/shared/core/
• core-activity-debounce.md · rules/shared/core/
• core-debug-storemap.md · rules/shared/core/
• core-debug-testing.md · rules/shared/core/
• core-encryption.md · rules/shared/core/
• core-event-subscription.md · rules/shared/core/
• core-install.md · rules/shared/core/
• core-message-stream.md · rules/shared/core/
• core-rest-api.md · rules/shared/core/
• core-store-array.md · rules/shared/core/
• core-store-lifecycle.md · rules/shared/core/
• core-store-map.md · rules/shared/core/
• core-store-subscribe.md · rules/shared/core/
• core-store-text.md · rules/shared/core/
• core-store-types.md · rules/shared/core/
• core-store-update.md · rules/shared/core/
• core-store-v2-api.md · rules/shared/core/
• core-store-xml.md · rules/shared/core/
• core-v1-to-v2-migration.md · rules/shared/core/
• core-velt-init.md · rules/shared/core/
• core-version-save.md · rules/shared/core/
• core-webhooks.md · rules/shared/core/
• tiptap-collaboration-manager.md · rules/shared/tiptap/
• tiptap-comments-integration.md · rules/shared/tiptap/
• tiptap-cursor-css.md · rules/shared/tiptap/
• tiptap-disable-history.md · rules/shared/tiptap/
• tiptap-editor-id.md · rules/shared/tiptap/
• tiptap-initial-content.md · rules/shared/tiptap/
• …and 3 more

SKILL.md (first lines)

# Velt CRDT Best Practices

Comprehensive best practices guide for implementing real-time collaborative editing with Velt CRDT (Yjs), maintained by Velt. Contains 42 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-v2-api` - **v2** Use `useStore<T>` + `useAwareness` React hooks; `createVeltStore` v2 config (`forceResetInitialContent`, `contentKey`, `userId`, `collection`, `logLevel`); reactive status/sync/error
- `core-v1-to-v2-migration` - Migration table: `useVeltCrdtStore` → `useStore` (`id` → `storeId`, new status/sync/error/onError, `useAwareness`)
- `core-store-create-vanilla` - Use createVeltStore for non-React (entry point unchanged in v2)
- `core-store-types` - Choose correct store type (text/array/map/xml/xmltext)
- `core-store-array` - Array store: useStore/createVeltStore with type:'array', Array.isArray() guard, add/remove item patterns
- `core-store-map` - Map store: useStore/createVeltStore with type:'map', object guard, key-level update/delete patterns
- `core-store-text` - Text store: useStore/createVeltStore with type:'text', textarea binding, null coalesce with ?? ''
- `core-store-xml` - XML store: NEVER call update(); mutate via store.getXml() (Y.XmlFragment) + Yjs APIs; requires npm i yjs
- `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
- `core-store-create-react` - *(v1 — DEPRECATED)* useVeltCrdtStore for React; see `core-v1-to-v2-migration`

### 2. Tiptap Integration (CRITICAL)

- `tiptap-install` - Install Tiptap CRDT v2 packages
- `tiptap-collaboration-manager` - **v2** Use useCollaboration / createCollaboration + CollaborationManager API
- `tiptap-v1-to-v2-migration` - Migration table: useVeltTiptapCrdtExtension → useCollaboration
- `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-initial-content` - Use HTML string format for initialContent
- `tiptap-comments-integration` - Integrate Velt Comments with Tiptap
- `tiptap-nextjs-ssr` - Next.js SSR considerations
- `tiptap-testing` - Test collaboration with multiple users
- `tiptap-setup-react` - *(v1 — DEPRECATED)* useVeltTiptapCrdtExtension for React; see migration rule
- `tiptap-setup-vanilla` - *(v1 — DEPRECATED)* createVeltTipTapStore for non-React; see migration rule

### 3. BlockNote Integration (HIGH)

- `blocknote-install` - Install BlockNote CRDT v2 packages
- `blocknote-collaboration-manager` - **v2** Use useCollaboration / createCollaboration + CollaborationManager API
- `blocknote-v1-to-v2-migration` - Migration table: useVeltBlockNoteCrdtExtension → useCollaboration
- `blocknote-editor-id` - Use unique editorId per instance
- `blocknote-testing` - Test collaboration with multiple users
- `blocknote-setup-react` - *(v1 — DEPRECATED)* useVeltBlockNoteCrdtExtension; see migration rule

### 4. CodeMirror Integration (HIGH)

- `codemirror-install` - Install CodeMirror CRDT v2 packages
- `codemirror-collaboration-manager` - **v2** Use useCollaboration / createCollaboration + CollaborationManager API
- `codemirror-v1-to-v2-migration` - Migration table: useVeltCodeMirrorCrdtExtension → useCollaboration
- `codemirror-ycollab` - Wire yCollab extension with manager.getCollaborationPrimitives()
- `codemirror-editor-id` - Use unique editorId per instance
- `codemirror-testing` - Test collaboration with multiple users
- `codemirror-setup-react` - *(v1 — DEPRECATED)* useVeltCodeMirrorCrdtExtension for React; see migration rule
- `codemirror-setup-vanilla` - *(v1 — DEPRECATED)* createVeltCodeMirrorStore for non-React; see migration rule

### 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

From velt-js/velt-plugin-cursor, MIT.