🔧
API
🧪
Tutorials
A Collaborative Editor
A five minute guide to make an editor collaborative
Yjs is a modular framework for syncing things in real-time - like editors!
This guide will walk you through the main concepts of Yjs. First, we are going to create a collaborative editor and sync it with clients. You will get introduced to Yjs documents and to providers, that allow you to sync through different network protocols. Next, we talk about Awareness & Presence which are very important aspects of collaborative software. I created a separate section for Offline Support that shows you how to create offline-ready applications by just adding a few lines of code. The last section is an in-depth guide to Shared Types.
If you are impatient jump to the live demo at the bottom of the page 😉
Let's get started by deciding on an editor to use. Yjs doesn't ship with a customized editor. There are already a lot of awesome open-source editors projects out there. Yjs supports many of them using extensions. Editor bindings are a concept in Yjs that allow us to bind the state of a third-party editor to a synceable Yjs document. This is a list of all known editor bindings:
For the purpose of this guide, we are going to use the Quill editor - a great rich-text editor that is easy to setup. For a complete reference on how to setup Quill I refer to their documentation. If you first require a basic introduction in npm and bundles, please refer to the webpack getting started guide and additionally setting up a development server.
JavaScript
HTML
Install
1
import Quill from 'quill'
2
import QuillCursors from 'quill-cursors'
3
4
Quill.register('modules/cursors', QuillCursors);
5
6
const quill = new Quill(document.querySelector('#editor'), {
7
modules: {
8
cursors: true,
9
toolbar: [
10
// adding some basic Quill content features
11
[{ header: [1, 2, false] }],
12
['bold', 'italic', 'underline'],
13
['image', 'code-block']
14
],
15
history: {
16
// Local undo shouldn't undo changes
17
// from remote users
18
userOnly: true
19
}
20
},
21
placeholder: 'Start collaborating...',
22
theme: 'snow' // 'bubble' is also great
23
})
Copied!
1
<link href="https://cdn.quilljs.com/1.3.6/quill.snow.css" rel="stylesheet">
2
3
<div id="editor" />
Copied!
1
npm i quill quill-cursors
Copied!
1
npm i yjs y-quill
Copied!
1
import * as Y from 'yjs'
2
import { QuillBinding } from 'y-quill'
3
4
// A Yjs document holds the shared data
5
const ydoc = new Y.Doc()
6
// Define a shared text type on the document
7
const ytext = ydoc.getText('quill')
8
9
// Create an editor-binding which
10
// "binds" the quill editor to a Y.Text type.
11
const binding = new QuillBinding(ytext, quill)
Copied!
The
ytext object is a shared data structure for representing text. It also supports formatting attributes (i.e. bold and italic). Yjs automatically resolves concurrent changes on shared data so we don't have to worry about conflict resolution anymore. Then we synchronize ytext with the quill editor and keep them in-sync using the QuillBinding. Almost all editor bindings work like this. You can simply exchange the editor binding if you switch to another editor.But don't stop here, the editor doesn't sync to other clients yet! We need to choose a provider or implement our own communication protocol to exchange document updates with other peers.
Each provider has pros and cons. The y-webrtc provider connects clients directly with each other and is a perfect choice for demo applications because it doesn't require you to set up a server. But for a real-world application, you often want to sync the document to a server. In any case, we got you covered. It is easy to change the provider because they all implement the same interface.
y-webrtc
y-websocket.
y-dat
Installation
1
import { WebrtcProvider } from 'y-webrtc'
2
3
const provider = new WebrtcProvider('quill-demo-room', ydoc)
Copied!
1
import { WebsocketProvider } from 'y-websocket'
2
3
// connect to the public demo server (not in production!)
4
const provider = new WebsocketProvider(
5
'wss://demos.yjs.dev', 'quill-demo-room', ydoc
6
)
Copied!
1
import { DatProvider } from 'y-dat'
2
3
// set null in order to create a fresh
4
const datKey = '7b0d584fcdaf1de2e8c473393a31f52327793931e03b330f7393025146dc02fb'
5
const provider = new DatProvider(datKey, ydoc)
Copied!
1
npm i y-webrtc # or
2
npm i y-websocket # or
3
npm i y-dat
Copied!
Providers work similarly to editor bindings. They sync Yjs documents through a communication protocol or a database. Most providers have in common that they use the concept of room-names to connect Yjs documents. In the above example, all documents that specify
'quill-demo-room' as the room-name will sync.Providers are meshable. You can connect multiple providers to a Yjs instance at the same time. Document updates will automatically sync through the different communication channels. Meshing providers can improve reliability through redundancy and decrease network delay.
By combining Yjs with providers and editor bindings we created our first collaborative editor. In the following sections, we will explore more Yjs concepts like awareness, shared types, and offline editing.
But for now, let's enjoy what we built. I included the same fiddle twice so you can observe the editors sync in real-time. Aware, the editor content is synced with all users visiting this page!
Last modified 8d ago
Copy link
Edit on GitHub