Skip to main content
The Yjs extension enables real-time collaborative editing using the Yjs CRDT (Conflict-free Replicated Data Type) library. Multiple users can edit the same document simultaneously with automatic conflict resolution.

​
Installation

Install Yjs peer dependencies: 
npm install yjs y-prosemirror
The Yjs extension is included in the prosekit package: 
import { defineYjs } from 'prosekit/extensions/yjs'

​
Styling

Import Yjs styles to show user selections: 
import 'prosekit/extensions/yjs/style.css'

​
Usage

import { createEditor } from 'prosekit/core'
import { defineYjs } from 'prosekit/extensions/yjs'
import * as Y from 'yjs'
import 'prosekit/extensions/yjs/style.css'

const ydoc = new Y.Doc()
const type = ydoc.getXmlFragment('prosemirror')

const editor = createEditor({
  extension: defineYjs({ 
    doc: ydoc,
    type: type 
  })
})

​
API reference

​
defineYjs(options)

Creates a Yjs extension for collaborative editing.
​
options.doc
Y.Doc
required
The Yjs document to sync with.
​
options.type
Y.XmlFragment
required
The Yjs XML fragment to use for the document. Typically obtained with doc.getXmlFragment('prosemirror').
​
options.prosemirrorOrigin
any
Origin identifier for ProseMirror transactions. Used to distinguish local vs remote changes.
​
options.colors
{ background: string, foreground: string }[]
Color palette for user selections. Defaults to a preset palette.

​
Complete example

See the Collaboration guide for a complete working example with WebSocket synchronization.

​
Key concepts

​
Y.Doc

A Yjs document contains shared data structures. Each client has its own instance that syncs with others. 
const ydoc = new Y.Doc()

​
Y.XmlFragment

The ProseMirror document is stored as an XML fragment in the Yjs document: 
const type = ydoc.getXmlFragment('prosemirror')

​
Network providers

Yjs supports various network providers:
  • y-websocket - WebSocket server synchronization
  • y-webrtc - Peer-to-peer WebRTC
  • y-indexeddb - Local persistence
import { WebsocketProvider } from 'y-websocket'

const provider = new WebsocketProvider(
  'wss://your-server.com',
  'room-name',
  ydoc
)

​
User awareness

Yjs includes awareness for showing user cursors and selections: 
import { WebsocketProvider } from 'y-websocket'

const provider = new WebsocketProvider('wss://server.com', 'room', ydoc)

// Set user information
provider.awareness.setLocalStateField('user', {
  name: 'Alice',
  color: '#2563eb',
})

​
Persistence

Save document state to IndexedDB: 
import { IndexeddbPersistence } from 'y-indexeddb'

const persistence = new IndexeddbPersistence('document-id', ydoc)

persistence.on('synced', () => {
  console.log('Content loaded from IndexedDB')
})

​
Offline support

Yjs automatically handles offline editing:
  1. Users can edit while offline
  2. Changes are queued locally
  3. When connection resumes, changes sync automatically
  4. Conflicts are resolved automatically

​
Custom colors

const editor = createEditor({
  extension: defineYjs({ 
    doc: ydoc,
    type: type,
    colors: [
      { background: '#fbbf2420', foreground: '#fbbf24' },
      { background: '#3b82f620', foreground: '#3b82f6' },
      { background: '#ef444420', foreground: '#ef4444' },
    ]
  })
})

​
Use cases

Collaborative documents

Multiple users editing the same document

Real-time notes

Shared note-taking and brainstorming

Team wikis

Collaborative knowledge bases

Offline-first apps

Apps that work without internet connection