CRDT (Yjs)

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.

Editors can send Yjs document updates. Viewers can receive and apply Yjs updates, but outbound Yjs writes are blocked for viewer sessions.

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.join({ role: 'editor' });

// 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

Property	Type	Description
`synced`	`boolean`	Whether 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.join({ role: 'editor' });

// 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:

Initial sync: On creation, the provider sends a crdtSyncRequest to the server, which returns the full document state.
Local changes: When the local Y.Doc is modified, the provider sends the delta as a crdtUpdate message.
Remote changes: The server broadcasts crdtUpdated messages to all other clients, which the provider applies to the local Y.Doc.
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.

Overview

Modules

Providers

Changelog

Installation

Import

Basic Usage

Constructor

Properties

Events

`synced`

Methods

`destroy()`

TipTap Integration

Multiple Documents

How It Works

​Installation

​Import

​Basic Usage

​Constructor

​Properties

​Events

​synced

​Methods

​destroy()

​TipTap Integration

​Multiple Documents

​How It Works

Installation

Import

Basic Usage

Constructor

Properties

Events

`synced`

Methods

`destroy()`

TipTap Integration

Multiple Documents

How It Works