@veltdev/reactflow-crdt library enables real-time collaborative editing on React Flow diagrams. The collaboration editing engine is built on top of Yjs and Velt SDK.
Prerequisites
- Node.js (v14 or higher)
- React (v16.8 or higher for hooks)
- A Velt account with an API key (sign up)
- Optional: TypeScript for type safety
Setup
Step 1: Install Dependencies
Install the required packages:Step 2: Setup Velt
Initialize the Velt client by following the Velt Setup Docs. This is required for the collaboration engine to work.Step 3: Initialize Velt CRDT Extension
- Initialize the Velt CRDT extension and use it to initialize the React Flow diagram.
- Pass an
editorIdto uniquely identify each diagram instance you have in your app. This is especially important when you have multiple diagrams in your app.
Notes
- Unique editorId: Use a unique
editorIdper diagram instance. - Use CRDT handlers: Always apply the store-provided
nodes,edges,onNodesChange,onEdgesChange, andonConnect.
Testing and Debugging
To test collaboration:- Login two unique users on two browser profiles and open the same page in both.
- Move nodes or create connections in one window and verify they sync in the other.
- Nodes/edges not syncing: Ensure each diagram has a unique
editorIdand the Velt client is initialized. Also ensure that you are logged in with two different users in two different browser profiles. - No updates on connect: Use the provided CRDT-aware
nodes,edges,onNodesChange/onEdgesChangeandonConnecthandlers from the store.
Complete Example
- Complete Code
- Live Demo
See Velt ReactFlow Demo Repo for our complete implementation.
Relevant Code
APIs
Custom Encryption
You can encrypt CRDT data before it’s stored in Velt by registering a custom encryption provider. For CRDT methods, input data is of typeUint8Array | number[].
- React / Next.js
- Other Frameworks
useVeltReactFlowCrdtExtension()
Provides real-time collaborative editing on React Flow diagrams with Yjs and Velt SDK.- Signature:
useVeltReactFlowCrdtExtension(config: VeltReactFlowCrdtExtensionConfig) - Params: VeltReactFlowCrdtExtensionConfig
editorId: Unique identifier for the diagram instance.initialNodes: Initial set of nodes.initialEdges: Initial set of edges.debounceMs: Debounce time for update propagation (ms).
- Returns: VeltReactFlowCrdtExtensionResponse
store: React Flow CRDT store instance.nodes: Array of nodes in the diagram.edges: Array of edges in the diagram.onNodesChange: CRDT-aware handler to apply node changes.onEdgesChange: CRDT-aware handler to apply edge changes.onConnect: CRDT-aware handler to apply connect changes.setNodes: Method to set nodessetEdges: Method to set edges
onNodesChange()
CRDT-aware handler to apply node changes (add/update/remove) that sync across collaborators.- Params: NodeChange[]
- Returns:
void
onEdgesChange()
CRDT-aware handler to apply edge changes (add/update/remove) that sync across collaborators.- Params: EdgeChange[]
- Returns:
void
onConnect()
CRDT-aware connect handler compatible with React Flow’s<ReactFlow onConnect={...} />.
- Params: Connection
- Returns:
void
setNodes()
Imperative setter for nodes (useful for non-event updates). Synced via the store.- Params: Node[]
- Returns:
void
setEdges()
Imperative setter for edges (useful for non-event updates). Synced via the store.- Params: Edge[]
- Returns:
void

