> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collab-kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CRDT (Yjs)

> Conflict-free collaborative editing with Yjs integration.

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.

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

## Installation

The Yjs provider is exported from a separate entry point. You also need `yjs` as a peer dependency:

```bash theme={null}
npm install yjs @collab-kit/client
```

## Import

```typescript theme={null}
import { CollabKitYjsProvider } from '@collab-kit/client/yjs';
import * as Y from 'yjs';
```

## Basic Usage

```typescript theme={null}
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

```typescript theme={null}
new CollabKitYjsProvider(client, ydoc, options);
```

<ParamField body="client" type="CollabKitClient" required>
  An initialized and connected `CollabKitClient` instance.
</ParamField>

<ParamField body="ydoc" type="Y.Doc" required>
  A Yjs document instance.
</ParamField>

<ParamField body="options.documentId" type="string" required>
  Unique identifier for the CRDT document within the room. Multiple documents can coexist in the same room by using different IDs.
</ParamField>

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

```typescript theme={null}
provider.on('synced', () => {
  console.log('Document is ready');
});
```

## Methods

### `destroy()`

Disconnect the provider and clean up resources:

```typescript theme={null}
provider.destroy();
```

## TipTap Integration

CollabKit's Yjs provider works with [TipTap](https://tiptap.dev/) and its collaboration extension:

```typescript theme={null}
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);
});
```

<Note>
  Disable TipTap's built-in `history` extension when using Collaboration. Yjs has its own undo/redo management.
</Note>

## Multiple Documents

You can create multiple providers for different documents within the same room:

```typescript theme={null}
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.