0
# @tiptap/extension-collaboration
1
2
The collaboration extension enables real-time collaborative editing in Tiptap editors using Yjs CRDT (Conflict-free Replicated Data Type). It provides seamless synchronization between multiple users editing the same document simultaneously, with built-in undo/redo functionality and conflict resolution. The extension runs at high priority (1000) to ensure proper initialization before other extensions.
3
4
## Package Information
5
6
- **Package Name**: @tiptap/extension-collaboration
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-collaboration`
10
11
## Core Imports
12
13
```typescript
14
import Collaboration from "@tiptap/extension-collaboration";
15
```
16
17
Or named import:
18
19
```typescript
20
import { Collaboration } from "@tiptap/extension-collaboration";
21
```
22
23
For CommonJS:
24
25
```javascript
26
const Collaboration = require("@tiptap/extension-collaboration").default;
27
```
28
29
## Basic Usage
30
31
```typescript
32
import { Editor } from "@tiptap/core";
33
import Collaboration from "@tiptap/extension-collaboration";
34
import * as Y from "yjs";
35
36
// Create a Y.js document
37
const ydoc = new Y.Doc();
38
39
// Configure the editor with collaboration
40
const editor = new Editor({
41
extensions: [
42
// ... other extensions
43
Collaboration.configure({
44
document: ydoc,
45
field: "default", // optional: Y.js fragment name
46
}),
47
],
48
});
49
50
// Typically used with a collaboration provider
51
import { WebrtcProvider } from "y-webrtc";
52
const provider = new WebrtcProvider("room-name", ydoc);
53
```
54
55
## Architecture
56
57
The collaboration extension integrates several key components:
58
59
- **Yjs Integration**: Uses Y.js CRDT for conflict-free collaborative editing
60
- **Sync Plugin**: Handles synchronization between Y.js document and Tiptap editor
61
- **Undo/Redo System**: Collaborative-aware undo/redo functionality
62
- **Provider Agnostic**: Works with any Y.js collaboration provider (WebRTC, WebSocket, etc.)
63
- **Content Validation**: Optional content checking and error handling
64
65
## Capabilities
66
67
### Collaboration Extension
68
69
The main extension that enables real-time collaborative editing with Y.js integration.
70
71
```typescript { .api }
72
/**
73
* Collaboration extension for real-time collaborative editing
74
*/
75
const Collaboration: Extension<CollaborationOptions, CollaborationStorage>;
76
77
interface CollaborationOptions {
78
/** Y.js document instance */
79
document?: Doc | null;
80
/** Y.js fragment name (default: 'default') */
81
field?: string;
82
/** Raw Y.js fragment (alternative to document + field) */
83
fragment?: XmlFragment | null;
84
/** Collaboration provider instance */
85
provider?: any | null;
86
/** Callback fired when content is initially rendered from Y.js */
87
onFirstRender?: () => void;
88
/** Options for the Y.js sync plugin */
89
ySyncOptions?: YSyncOpts;
90
/** Options for the Y.js undo plugin */
91
yUndoOptions?: YUndoOpts;
92
}
93
94
interface CollaborationStorage {
95
/** Whether collaboration is currently disabled */
96
isDisabled: boolean;
97
}
98
```
99
100
**Usage Example:**
101
102
```typescript
103
import Collaboration from "@tiptap/extension-collaboration";
104
import * as Y from "yjs";
105
106
const ydoc = new Y.Doc();
107
108
const editor = new Editor({
109
extensions: [
110
Collaboration.configure({
111
document: ydoc,
112
field: "content", // custom fragment name
113
onFirstRender: () => {
114
console.log("Initial content loaded from Y.js");
115
},
116
}),
117
],
118
});
119
```
120
121
### Collaboration Commands
122
123
The extension adds undo and redo commands to the editor with collaborative awareness.
124
125
```typescript { .api }
126
/**
127
* Undo recent changes in collaborative context
128
*/
129
editor.commands.undo(): boolean;
130
131
/**
132
* Reapply reverted changes in collaborative context
133
*/
134
editor.commands.redo(): boolean;
135
```
136
137
**Usage Example:**
138
139
```typescript
140
// Programmatic undo/redo
141
editor.commands.undo();
142
editor.commands.redo();
143
144
// Check if undo/redo is available
145
const canUndo = editor.can().undo();
146
const canRedo = editor.can().redo();
147
```
148
149
### Change Origin Detection
150
151
Utility function to check if a ProseMirror transaction originated from a Y.js change.
152
153
```typescript { .api }
154
/**
155
* Checks if a transaction was originated from a Yjs change
156
* @param transaction - The ProseMirror transaction to check
157
* @returns True if the transaction originated from Yjs change
158
*/
159
function isChangeOrigin(transaction: Transaction): boolean;
160
```
161
162
**Usage Example:**
163
164
```typescript
165
import { isChangeOrigin } from "@tiptap/extension-collaboration";
166
167
editor.on("transaction", ({ transaction }) => {
168
if (isChangeOrigin(transaction)) {
169
console.log("This change came from another collaborator");
170
} else {
171
console.log("This change was made locally");
172
}
173
});
174
```
175
176
### Storage Access
177
178
Access collaboration state through the editor's storage system.
179
180
```typescript { .api }
181
/**
182
* Access collaboration storage
183
*/
184
editor.storage.collaboration: CollaborationStorage;
185
```
186
187
**Usage Example:**
188
189
```typescript
190
// Check if collaboration is disabled
191
const isDisabled = editor.storage.collaboration.isDisabled;
192
193
// Disable collaboration (prevents sync with other users)
194
editor.storage.collaboration.isDisabled = true;
195
```
196
197
## Types
198
199
```typescript { .api }
200
// Y.js types (from yjs package)
201
interface Doc {
202
getXmlFragment(name: string): XmlFragment;
203
destroy(): void;
204
}
205
206
interface XmlFragment {
207
doc?: Doc;
208
}
209
210
interface UndoManager {
211
undoStack: any[];
212
redoStack: any[];
213
trackedOrigins: Set<any>;
214
restore?: () => void;
215
doc: Doc;
216
afterTransactionHandler: (transaction: any, doc: Doc) => void;
217
_observers: any;
218
}
219
220
// ProseMirror types (from @tiptap/pm packages)
221
interface Transaction {
222
getMeta(key: any): any;
223
setMeta(key: string, value: any): Transaction;
224
}
225
226
// Plugin configuration types
227
type YSyncOpts = Parameters<typeof ySyncPlugin>[1];
228
type YUndoOpts = Parameters<typeof yUndoPlugin>[0];
229
```
230
231
## Error Handling
232
233
The extension includes content validation when `editor.options.enableContentCheck` is enabled. This validates Y.js document content against the ProseMirror schema before applying transactions:
234
235
```typescript
236
editor.on("contentError", ({ error, editor, disableCollaboration }) => {
237
console.error("Collaboration content error:", error);
238
239
// Optionally disable collaboration to prevent further issues
240
disableCollaboration();
241
});
242
```
243
244
When content validation is enabled, the extension:
245
- Checks Y.js fragment content against the editor schema before each transaction
246
- Emits `contentError` events when invalid content is detected
247
- Provides a `disableCollaboration()` callback to stop synchronization
248
- Filters invalid transactions when collaboration is disabled
249
- Automatically destroys the Y.js document when disabled to prevent further sync
250
251
## Compatibility
252
253
**Important**: This extension includes its own undo/redo functionality and is **not compatible** with `@tiptap/extension-undo-redo`. Using both extensions together will cause conflicts. The collaboration extension will log a warning if it detects the presence of the undoRedo extension.
254
255
## Keyboard Shortcuts
256
257
The extension automatically adds collaborative undo/redo keyboard shortcuts:
258
259
- **Cmd/Ctrl + Z**: Undo
260
- **Cmd/Ctrl + Y**: Redo
261
- **Cmd/Ctrl + Shift + Z**: Redo (alternative)
262
263
## Dependencies
264
265
**Peer Dependencies:**
266
- `@tiptap/core` - Core Tiptap framework
267
- `@tiptap/pm` - ProseMirror packages for Tiptap
268
- `@tiptap/y-tiptap` - Y.js integration for Tiptap
269
- `yjs` - Y.js CRDT library
270
271
**Provider Examples:**
272
- `y-webrtc` - WebRTC-based collaboration
273
- `y-websocket` - WebSocket-based collaboration
274
- `y-indexeddb` - Local persistence