@veltdev/tiptap-crdt-react
library enables real-time collaborative editing on Tiptap Editors. 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 Tiptap editor.
- Pass an
editorId
to uniquely identify each editor instance you have in your app. This is especially important when you have multiple editors in your app.
Notes
- Unique editorId: Use a unique
editorId
per editor instance. - Disable history: Turn off Tiptap
history
when using collaboration. - Auth required: Ensure the Velt client is initialized and user is available before starting.
Testing and Debugging
To test collaboration:- Login two unique users on two browser profiles and open the same page in both.
- Edit in one window and verify changes and cursors appear in the other.
- Cursors not appearing: Ensure each editor has a unique
editorId
and users are authenticated. Also ensure that you are logged in with two different users in two different browser profiles. - Editor not loading: Confirm the Velt client is initialized and the API key is valid.
- Desynced content: Make sure Tiptap
history
is disabled when using collaboration.
Complete Example
See Velt Tiptap Demo Repo for our complete implementation.
Relevant Code
APIs
Custom Encryption
Encrypt CRDT data before it’s stored in Velt by registering a custom encryption provider. For CRDT methods, input data is of typeUint8Array | number[]
.
useVeltTiptapCrdtExtension()
Provides real-time collaborative editing on Tiptap editor with Yjs and Velt SDK.- Signature:
useVeltTiptapCrdtExtension(config: VeltTiptapCrdtExtensionConfig)
- Params: VeltTiptapCrdtExtensionConfig
editorId
: Unique identifier for the editor instance.initialContent
: Initial content for the editor.debounceMs
: Debounce time for update propagation (ms).
- Returns: VeltTiptapCrdtExtensionResponse
VeltCrdt
: Tiptap Velt CRDT Extension.store
: Tiptap CRDT store instance.isLoading
: Whether the store is initialized.false
once store is initialized,true
by default.
Store Methods
store.getStore()
Access the underlying CRDT store managing document state.- Returns: Store
store.destroy()
Tear down the store and clean up listeners/resources.- Returns: void
store.getYDoc()
Accessor for the underlying Yjs document.- Returns: Y.Doc
store.getYXml()
Returns the Y.XmlFragment instance that handles Tiptap’s rich text structure.- Returns: Y.XmlFragment | null