@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
editorId
to 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
editorId
per 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
editorId
and 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
/onEdgesChange
andonConnect
handlers 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