0
# Yjs
1
2
Yjs is a framework for offline-first peer-to-peer shared editing on structured data like text, richtext, JSON, or XML. It provides a modular architecture where users combine connectors (WebRTC, WebSockets, XMPP), database adapters (memory, IndexedDB, LevelDB), and data types (Map, Array, Text, XML, RichText) to build collaborative editing applications. The framework hides the complexity of concurrent editing by automatically resolving conflicts through its CRDT-based approach.
3
4
## Package Information
5
6
- **Package Name**: yjs
7
- **Package Type**: bower
8
- **Language**: JavaScript
9
- **Installation**: `bower install yjs`
10
- **Documentation**: http://y-js.org/
11
12
## Core Imports
13
14
For browser environments:
15
16
```javascript
17
// Manual script inclusion
18
<script src="/bower_components/yjs/y.js"></script>
19
```
20
21
For Node.js/CommonJS environments:
22
23
```javascript
24
const Y = require('yjs');
25
```
26
27
## Basic Usage
28
29
```javascript
30
// Create a Yjs instance with configuration
31
Y({
32
db: { name: 'memory' },
33
connector: {
34
name: 'websockets-client',
35
room: 'my-collaborative-room',
36
url: 'ws://localhost:1234'
37
},
38
sourceDir: '/bower_components',
39
share: {
40
textarea: 'Text',
41
chat: 'Array',
42
drawing: 'Map'
43
}
44
}).then(function (y) {
45
// Access shared types
46
y.share.textarea.bind(document.getElementById('editor'));
47
48
// Listen for changes
49
y.share.chat.observe(function(event) {
50
console.log('Chat updated:', event);
51
});
52
53
// Add data
54
y.share.chat.push(['Hello from user!']);
55
y.share.drawing.set('stroke1', { x: 10, y: 20, color: 'red' });
56
});
57
```
58
59
## Architecture
60
61
Yjs is built around several key components:
62
63
- **Y Constructor**: Main factory function that creates configured Yjs instances
64
- **Modular System**: Extensible architecture with pluggable connectors and databases
65
- **Shared Types**: CRDT-based data structures (Array, Map, Text, XML, RichText) that automatically sync
66
- **Connector Layer**: Communication protocols for peer-to-peer synchronization
67
- **Database Layer**: Persistence and storage backends with garbage collection
68
- **Event System**: Observable pattern for real-time change notifications
69
70
## Capabilities
71
72
### Instance Creation and Configuration
73
74
Primary constructor and configuration system for creating Yjs collaborative instances.
75
76
```javascript { .api }
77
/**
78
* Creates a new Yjs instance with specified configuration
79
* @param {YjsOptions} options - Configuration object
80
* @returns {Promise<YjsInstance>} Promise resolving to configured Yjs instance
81
*/
82
function Y(options);
83
84
interface YjsOptions {
85
db: DatabaseConfig;
86
connector: ConnectorConfig;
87
sourceDir?: string;
88
share: ShareConfig;
89
type?: string[];
90
}
91
92
interface DatabaseConfig {
93
name: 'memory' | 'indexeddb' | 'leveldb';
94
}
95
96
interface ConnectorConfig {
97
name: 'webrtc' | 'websockets-client' | 'xmpp' | 'test';
98
room: string;
99
url?: string;
100
auth?: any;
101
checkAuth?: Function;
102
generateUserId?: boolean;
103
}
104
105
interface ShareConfig {
106
[key: string]: 'Array' | 'Map' | 'Text' | 'Xml' | 'RichText';
107
}
108
```
109
110
[Instance Management](./instance-management.md)
111
112
### Shared Data Types
113
114
CRDT-based collaborative data structures for different use cases, from simple arrays to rich text editing.
115
116
```javascript { .api }
117
interface SharedArray {
118
/** Number of items in the array */
119
length: number;
120
push(items: any[]): void;
121
delete(index: number, length?: number): void;
122
get(index: number): any;
123
insert(index: number, items: any[]): void;
124
toArray(): any[];
125
observe(callback: (event: ArrayEvent) => void): void;
126
}
127
128
interface SharedMap {
129
set(key: string, value: any): void;
130
get(key: string): any;
131
delete(key: string): void;
132
observe(callback: (event: MapEvent) => void): void;
133
}
134
135
interface SharedText {
136
bind(element: HTMLElement): void;
137
bindMonaco(editor: any): void;
138
bindAce(editor: any): void;
139
bindCodeMirror(editor: any): void;
140
observe(callback: (event: TextEvent) => void): void;
141
}
142
```
143
144
[Shared Types](./shared-types.md)
145
146
### Connection Management
147
148
Real-time synchronization and peer-to-peer communication management.
149
150
```javascript { .api }
151
interface YjsConnector {
152
onUserEvent(callback: (event: UserEvent) => void): void;
153
whenSynced(callback: () => void): void;
154
disconnect(): void;
155
reconnect(): void;
156
isSynced: boolean;
157
}
158
```
159
160
[Connection Management](./connection-management.md)
161
162
### Database and Persistence
163
164
Data persistence layer with garbage collection and transaction management.
165
166
```javascript { .api }
167
interface YjsDatabase {
168
stopGarbageCollector(): void;
169
gc: boolean;
170
gcTimeout: number;
171
userId: string;
172
}
173
```
174
175
[Database Operations](./database-operations.md)
176
177
### Extension System
178
179
Framework for creating custom connectors, databases, and shared types.
180
181
```javascript { .api }
182
/**
183
* Extend Yjs with additional modules
184
* @param {...any} modules - Modules to add to Yjs
185
*/
186
function Y.extend(...modules);
187
188
/**
189
* Array constructor for creating nested array types
190
*/
191
Y.Array;
192
193
/**
194
* Map constructor for creating nested map types
195
*/
196
Y.Map;
197
198
/**
199
* Text constructor for creating nested text types
200
*/
201
Y.Text;
202
203
class Y.AbstractConnector {
204
// Base class for custom connectors
205
}
206
207
class Y.AbstractDatabase {
208
// Base class for custom database adapters
209
}
210
```
211
212
[Extensions](./extensions.md)
213
214
## Types
215
216
```javascript { .api }
217
interface YjsInstance {
218
share: ShareInstances;
219
connector: YjsConnector;
220
db: YjsDatabase;
221
isConnected(): boolean;
222
disconnect(): void;
223
reconnect(): void;
224
close(): void;
225
destroy(): void;
226
}
227
228
interface ShareInstances {
229
[key: string]: SharedArray | SharedMap | SharedText | SharedXml | SharedRichText;
230
}
231
232
interface ArrayEvent {
233
type: 'insert' | 'delete';
234
index: number;
235
length: number;
236
values?: any[];
237
}
238
239
interface MapEvent {
240
type: 'add' | 'update' | 'delete';
241
name: string;
242
value?: any;
243
oldValue?: any;
244
}
245
246
interface TextEvent {
247
type: 'insert' | 'delete';
248
index: number;
249
length: number;
250
values?: string[];
251
}
252
253
interface UserEvent {
254
action: 'userJoined' | 'userLeft';
255
user: string;
256
}
257
```