velt-js/agent-skills

Overview

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.

How this skill works

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.

When to use it

• Setting up Velt client and creating CRDT stores for a new feature
• Integrating collaborative editing with Tiptap, BlockNote, CodeMirror, or ReactFlow
• Debugging sync issues, merging conflicts, or unexpected state divergence
• Implementing version checkpoints, server-side snapshots, or encryption for sensitive data
• Designing automated tests or manual multi-user validation for real-time flows

Best practices

• Initialize the Velt client before creating or accessing any CRDT stores to avoid race conditions
• Choose the correct store type (text/array/map/xml) and use store.update() and subscriptions for state changes
• Use editor-specific extensions/hooks: useVeltTiptapCrdtExtension, useVeltBlockNoteCrdtExtension, useVeltCodeMirrorCrdtExtension, useVeltReactFlowCrdtExtension
• Assign a unique editorId per instance and disable local editor history where it conflicts with CRDT history (e.g., Tiptap)
• Test collaboration with multiple browser profiles and use store maps and checkpoints for debugging and version recovery
• Protect sensitive data with a custom encryption provider and use webhooks or server REST API calls for server-side workflows

Example use cases

• Real-time rich-text editor powered by Tiptap with Velt CRDT stores and collaboration cursors
• Collaborative code editor using CodeMirror wired to yCollab and Velt stores for shared editing
• Block-based document editor (BlockNote) with per-editor IDs, version checkpoints, and replayable history
• Multi-user graph editor with ReactFlow where node/edge changes are synchronized via CRDT handlers
• Server-side snapshot retrieval and audits using CRDT REST API and webhook triggers for change events