Skip to main content
CollabKit provides a Yjs provider that bridges a Y.Doc to the server via the existing WebSocket connection. This enables real-time collaborative editing with conflict-free resolution — no additional infrastructure required.

​
Installation

The Yjs provider is exported from a separate entry point. You also need yjs as a peer dependency: 
npm install yjs @collab-kit/client

​
Import

import { CollabKitYjsProvider } from '@collab-kit/client/yjs';
import * as Y from 'yjs';

​
Basic Usage

import CollabKitClient from '@collab-kit/client';
import { CollabKitYjsProvider } from '@collab-kit/client/yjs';
import * as Y from 'yjs';

const client = new CollabKitClient({
  serverUrl: 'https://api.collab-kit.com',
  authToken: '<jwt>',
});

await client.connect();
await client.join();

// Create a Yjs document
const ydoc = new Y.Doc();

// Bind it to CollabKit
const provider = new CollabKitYjsProvider(client, ydoc, {
  documentId: 'main-editor',
});

// Wait for initial sync from server
provider.on('synced', () => {
  console.log('Document loaded from server');
});

​
Constructor

new CollabKitYjsProvider(client, ydoc, options);
​
client
CollabKitClient
required
An initialized and connected CollabKitClient instance.
​
ydoc
Y.Doc
required
A Yjs document instance.
​
options.documentId
string
required
Unique identifier for the CRDT document within the room. Multiple documents can coexist in the same room by using different IDs.

​
Properties

PropertyTypeDescription
syncedbooleanWhether the initial sync from the server is complete

​
Events

​
synced

Fires when the initial document state has been loaded from the server: 
provider.on('synced', () => {
  console.log('Document is ready');
});

​
Methods

​
destroy()

Disconnect the provider and clean up resources: 
provider.destroy();

​
TipTap Integration

CollabKit’s Yjs provider works with TipTap and its collaboration extension: 
import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';
import Collaboration from '@tiptap/extension-collaboration';
import CollabKitClient from '@collab-kit/client';
import { CollabKitYjsProvider } from '@collab-kit/client/yjs';
import * as Y from 'yjs';

// Set up CollabKit
const client = new CollabKitClient({
  serverUrl: 'https://api.collab-kit.com',
  authToken: '<jwt>',
});
await client.connect();
await client.join();

// Set up Yjs
const ydoc = new Y.Doc();
const provider = new CollabKitYjsProvider(client, ydoc, {
  documentId: 'main-editor',
});

// Create the editor
const editor = new Editor({
  element: document.getElementById('editor'),
  extensions: [
    StarterKit.configure({ history: false }), // Disable built-in undo
    Collaboration.configure({ document: ydoc }),
  ],
});

// Wait for sync before allowing edits
provider.on('synced', () => {
  editor.setEditable(true);
});
Disable TipTap’s built-in history extension when using Collaboration. Yjs has its own undo/redo management.

​
Multiple Documents

You can create multiple providers for different documents within the same room: 
const ydocEditor = new Y.Doc();
const ydocCanvas = new Y.Doc();

const editorProvider = new CollabKitYjsProvider(client, ydocEditor, {
  documentId: 'editor',
});

const canvasProvider = new CollabKitYjsProvider(client, ydocCanvas, {
  documentId: 'canvas',
});

​
How It Works

The Yjs provider uses CollabKit’s WebSocket connection to synchronize document state:
  1. Initial sync: On creation, the provider sends a crdtSyncRequest to the server, which returns the full document state.
  2. Local changes: When the local Y.Doc is modified, the provider sends the delta as a crdtUpdate message.
  3. Remote changes: The server broadcasts crdtUpdated messages to all other clients, which the provider applies to the local Y.Doc.
  4. Persistence: The server stores the document state in its SQLite database. Documents survive server restarts.
No additional server configuration is needed — CRDT support is built into the CollabKit server.