4e:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 4f:T5191,--- title: Collaboration description: Real-time collaboration with Yjs toc: true --- ## Features - **Multi-Provider Support:** Enables real-time collaboration using [Yjs](https://github.com/yjs/yjs) and [slate-yjs](https://docs.slate-yjs.dev/). Supports multiple synchronization providers simultaneously (e.g., IndexedDB + Hocuspocus + WebRTC) working on a shared `Y.Doc`. - **Built-in Providers:** Includes support for [IndexedDB](https://github.com/yjs/y-indexeddb) local persistence, [Hocuspocus](https://tiptap.dev/hocuspocus) server-based collaboration, and [WebRTC](https://github.com/yjs/y-webrtc) peer-to-peer collaboration. - **Custom Providers:** Extensible architecture allows adding custom providers by implementing the `UnifiedProvider` interface. - **Awareness & Cursors:** Integrates Yjs Awareness protocol for sharing cursor locations and other ephemeral state between users. Includes [`RemoteCursorOverlay`](/docs/components/remote-cursor-overlay) for rendering remote cursors. - **Customizable Cursors:** Cursor appearance (name, color) can be customized via `cursors`. - **Manual Lifecycle:** Provides explicit `init` and `destroy` methods for managing the Yjs connection lifecycle. ## Usage ### Installation Install the core Yjs plugin. ```bash npm install @platejs/yjs ``` For Hocuspocus server-based collaboration: ```bash npm install @hocuspocus/provider ``` For WebRTC peer-to-peer collaboration: ```bash npm install y-webrtc ``` ### Add Plugin ```tsx import { YjsPlugin } from '@platejs/yjs/react'; import { createPlateEditor } from 'platejs/react'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, YjsPlugin, ], // Important: Skip Plate's default initialization when using Yjs skipInitialization: true, }); ``` It's crucial to set `skipInitialization: true` when creating the editor. Yjs manages the initial document state, so Plate's default value initialization should be skipped to avoid conflicts. ### Configure YjsPlugin Configure the plugin with providers and cursor settings: ```tsx import { YjsPlugin } from '@platejs/yjs/react'; import { createPlateEditor } from 'platejs/react'; import { RemoteCursorOverlay } from '@/components/ui/remote-cursor-overlay'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, YjsPlugin.configure({ render: { afterEditable: RemoteCursorOverlay, }, options: { // Configure local user cursor appearance cursors: { data: { name: 'User Name', // Replace with dynamic user name color: '#aabbcc', // Replace with dynamic user color }, }, // Configure providers. All providers share the same Y.Doc and Awareness instance. providers: [ // Example: IndexedDB provider for local persistence { type: 'indexeddb', options: { docName: 'my-document-id', // Unique IndexedDB database name }, }, // Example: Hocuspocus provider { type: 'hocuspocus', options: { name: 'my-document-id', // Unique identifier for the document url: 'ws://localhost:8888', // Your Hocuspocus server URL }, }, // Example: WebRTC provider (can be used alongside Hocuspocus) { type: 'webrtc', options: { roomName: 'my-document-id', // Must match the document identifier signaling: ['ws://localhost:4444'], // Optional: Your signaling server URLs }, }, ], }, }), ], skipInitialization: true, }); ``` - `render.afterEditable`: Assigns [`RemoteCursorOverlay`](/docs/components/remote-cursor-overlay) to render remote user cursors. - `cursors.data`: Configures the local user's cursor appearance with name and color. - `providers`: Array of collaboration providers to use (Hocuspocus, WebRTC, or custom providers). ### Add Editor Container The `RemoteCursorOverlay` requires a positioned container around the editor content. Use [`EditorContainer`](/docs/components/editor) component or `PlateContainer` from `platejs/react`: ```tsx import { Plate } from 'platejs/react'; import { EditorContainer } from '@/components/ui/editor'; return ( ); ``` ### Initialize Yjs Connection Yjs connection and state initialization are handled manually, typically within a `useEffect` hook: ```tsx import React, { useEffect } from 'react'; import { YjsPlugin } from '@platejs/yjs/react'; import { useMounted } from '@/hooks/use-mounted'; // Or your own mounted check const MyEditorComponent = ({ documentId, initialValue }) => { const editor = usePlateEditor(/** editor config from previous steps **/); const mounted = useMounted(); useEffect(() => { // Ensure component is mounted and editor is ready if (!mounted) return; // Initialize Yjs connection, sync document, and set initial editor state editor.getApi(YjsPlugin).yjs.init({ id: documentId, // Unique identifier for the Yjs document value: initialValue, // Initial content if the Y.Doc is empty }); // Clean up: Destroy connection when component unmounts return () => { editor.getApi(YjsPlugin).yjs.destroy(); }; }, [editor, mounted]); return ( ); }; ``` **Initial Value**: The `value` passed to `init` is only used to populate the Y.Doc if it's completely empty on the backend/peer network. If the document already exists, its content will be synced, and this initial value will be ignored. **Lifecycle Management**: You **must** call `editor.api.yjs.init()` to establish the connection and `editor.api.yjs.destroy()` on component unmount to clean up resources. ### Monitor Connection Status (Optional) Access provider states and add event handlers for connection monitoring: ```tsx import React from 'react'; import { YjsPlugin } from '@platejs/yjs/react'; import { usePluginOption } from 'platejs/react'; function EditorStatus() { // Access provider states directly (read-only) const providers = usePluginOption(YjsPlugin, '_providers'); const isConnected = usePluginOption(YjsPlugin, '_isConnected'); return (

{providers.map((provider) => ( {provider.type}: {provider.isConnected ? 'Connected' : 'Disconnected'} ({provider.isSynced ? 'Synced' : 'Syncing'}) ))}

); } // Add event handlers for connection events: YjsPlugin.configure({ options: { // ... other options onConnect: ({ type }) => console.debug(`Provider ${type} connected!`), onDisconnect: ({ type }) => console.debug(`Provider ${type} disconnected.`), onSyncChange: ({ type, isSynced }) => console.debug(`Provider ${type} sync status: ${isSynced}`), onError: ({ type, error }) => console.error(`Error in provider ${type}:`, error), }, }); ``` ## Provider Types ### Hocuspocus Provider Server-based collaboration using [Hocuspocus](https://tiptap.dev/hocuspocus). Requires a running Hocuspocus server. ```tsx type HocuspocusProviderConfig = { type: 'hocuspocus', options: { name: string; // Document identifier url: string; // WebSocket server URL token?: string; // Authentication token wsOptions?: HocuspocusProviderWebsocketConfiguration; // Advanced websocket config (headers, protocols, etc.) } } ``` #### `wsOptions` You can pass a `wsOptions` field to configure advanced websocket options for the Hocuspocus provider. This is useful for custom headers, authentication, protocols, or other websocket settings supported by [`HocuspocusProviderWebsocket`](https://tiptap.dev/hocuspocus/api/provider#websocket-configuration). Example usage: ```tsx { type: 'hocuspocus', options: { name: 'my-document-id', }, wsOptions: { url: 'ws://localhost:8888', maxAttempts: 5, parameters: { // request parameters } }, } ``` ### WebRTC Provider Peer-to-peer collaboration using [y-webrtc](https://github.com/yjs/y-webrtc). ```tsx type WebRTCProviderConfig = { type: 'webrtc', options: { roomName: string; // Room name for collaboration signaling?: string[]; // Signaling server URLs password?: string; // Room password maxConns?: number; // Max connections peerOpts?: object; // WebRTC peer options } } ``` ### IndexedDB Provider Local browser persistence using [y-indexeddb](https://github.com/yjs/y-indexeddb). Use it alongside a network provider when the editor should restore local state before remote sync finishes. ```tsx type IndexeddbProviderConfig = { type: 'indexeddb', options: { docName: string; // Stable IndexedDB database name for this document } } ``` ### Custom Provider Create custom providers by implementing the `UnifiedProvider` interface: ```typescript interface UnifiedProvider { awareness: Awareness; document: Y.Doc; type: string; connect: () => void; destroy: () => void; disconnect: () => void; isConnected: boolean; isSynced: boolean; } ``` Use custom providers directly in the providers array: ```tsx const customProvider = new MyCustomProvider({ doc: ydoc, awareness }); YjsPlugin.configure({ options: { providers: [customProvider], }, }); ``` ## Backend Setup ### IndexedDB Local Persistence IndexedDB runs in the browser and uses the shared `Y.Doc` created by `YjsPlugin`. Use the same document identifier for `docName` and your network provider room/name when you combine providers: ```tsx { type: 'indexeddb', options: { docName: 'document-1', }, } ``` IndexedDB does not transport remote awareness or cursors. It persists document updates locally; Hocuspocus or WebRTC still own multi-user transport. ### Hocuspocus Server Set up a [Hocuspocus server](https://tiptap.dev/hocuspocus/getting-started) for server-based collaboration. Ensure the `url` and `name` in your provider options match your server configuration. ### WebRTC Setup #### Signaling Server WebRTC requires signaling servers for peer discovery. Public servers work for testing but use your own for production: ```bash npm install y-webrtc PORT=4444 node ./node_modules/y-webrtc/bin/server.js ``` Configure your client to use custom signaling: ```tsx { type: 'webrtc', options: { roomName: 'document-1', signaling: ['ws://your-signaling-server.com:4444'], }, } ``` #### TURN Servers WebRTC connections can fail due to firewalls. Use TURN servers or combine with Hocuspocus for production reliability. Configure TURN servers for reliable connections: ```tsx { type: 'webrtc', options: { roomName: 'document-1', signaling: ['ws://your-signaling-server.com:4444'], peerOpts: { config: { iceServers: [ { urls: 'stun:stun.l.google.com:19302' }, { urls: 'turn:your-turn-server.com:3478', username: 'username', credential: 'password' } ] } } } } ``` ## Security **Authentication & Authorization:** - Use Hocuspocus's `onAuthenticate` hook to validate users - Implement document-level access control on your backend - Pass authentication tokens via the `token` option **Transport Security:** - Use `wss://` URLs in production for encrypted communication - Configure secure TURN servers with the `turns://` protocol **WebRTC Security:** - Use the `password` option for basic room access control - Configure secure signaling servers Example secure configuration: ```tsx YjsPlugin.configure({ options: { providers: [ { type: 'hocuspocus', options: { name: 'secure-document-id', url: 'wss://your-hocuspocus-server.com', token: 'user-auth-token', }, }, { type: 'webrtc', options: { roomName: 'secure-document-id', password: 'strong-room-password', signaling: ['wss://your-secure-signaling.com'], peerOpts: { config: { iceServers: [ { urls: 'turns:your-turn-server.com:443?transport=tcp', username: 'user', credential: 'pass' } ] } } }, }, ], }, }); ``` ## Troubleshooting ### Connection Issues **Check URLs and Names:** - Verify `url` (Hocuspocus) and `signaling` URLs (WebRTC) are correct - Ensure `docName`, `name`, or `roomName` matches exactly across providers that share one document - Use `ws://` for local development, `wss://` for production **Server Status:** - Verify Hocuspocus and signaling servers are running - Check server logs for errors - Test TURN server connectivity if using WebRTC **Network Issues:** - Firewalls may block WebSocket or WebRTC traffic - Use TURN servers configured for TCP (port 443) for better traversal - Check browser console for provider errors ### Multiple Documents **Separate Instances:** - Create separate `Y.Doc` instances for each document - Use unique document identifiers for `name`/`roomName` - Pass unique `ydoc` and `awareness` instances to each editor ### Sync Issues **Editor Initialization:** - Always set `skipInitialization: true` when creating the editor - Use `editor.api.yjs.init({ value })` for initial content - Ensure all providers use the exact same document identifier **Content Conflicts:** - Avoid manually manipulating the shared `Y.Doc` - Let Yjs handle all document operations through the editor ### Cursor Issues **Overlay Setup:** - Include [`RemoteCursorOverlay`](/docs/components/remote-cursor-overlay) in plugin render config - Use positioned container (`EditorContainer` or `PlateContainer`) - Verify `cursors.data` (name, color) is set correctly for local user ## Related - [Yjs](https://github.com/yjs/yjs) - CRDT framework for collaboration - [slate-yjs](https://docs.slate-yjs.dev/) - Yjs bindings for Slate - [y-indexeddb](https://github.com/yjs/y-indexeddb) - IndexedDB persistence provider - [Hocuspocus](https://tiptap.dev/hocuspocus) - Backend server for Yjs - [y-webrtc](https://github.com/yjs/y-webrtc) - WebRTC provider - [RemoteCursorOverlay](/docs/components/remote-cursor-overlay) - Remote cursor component - [EditorContainer](/docs/components/editor) - Editor container component ## Plugins ### `YjsPlugin` Enables real-time collaboration using Yjs with support for multiple providers and remote cursors. Array of provider configurations or pre-instantiated provider instances. The plugin will create instances from configurations and use existing instances directly. All providers will share the same Y.Doc and Awareness. Each configuration object specifies a provider `type` (for example `'indexeddb'`, `'hocuspocus'`, or `'webrtc'`) and its specific `options`. Custom provider instances must conform to the `UnifiedProvider` interface. Configuration for remote cursors. Set to `null` to explicitly disable cursors. If omitted, cursors are enabled by default if providers are specified. Passed to `withTCursors`. See [WithCursorsOptions API](https://docs.slate-yjs.dev/api/slate-yjs-core/cursor-plugin#withcursors). Includes `data` for local user info and `autoSend` (default `true`). Optional shared Y.Doc instance. If not provided, a new one will be created internally by the plugin. Provide your own if integrating with other Yjs tools or managing multiple documents. Optional shared Awareness instance. If not provided, a new one will be created. Callback fired when any provider successfully connects. Callback fired when any provider disconnects. Callback fired when any provider encounters an error (e.g., connection failure). Callback fired when the sync status (`provider.isSynced`) of any individual provider changes. {/* Attributes are internal state, generally use options or event handlers instead */} Internal state: Whether at least one provider is currently connected. Internal state: Reflects overall sync status. Internal state: Array of all active, instantiated provider instances. ## API ### `api.yjs.init` Initializes the Yjs connection, binds it to the editor, sets up providers based on plugin configuration, potentially populates the Y.Doc with initial content, and connects providers. **Must be called after the editor is mounted.** Configuration object for initialization. A unique identifier for the Yjs document (e.g., room name, document ID). If not provided, `editor.id` is used. Essential for ensuring collaborators connect to the same document state. The initial content for the editor. **This is only applied if the Y.Doc associated with the `id` is completely empty in the shared state (backend/peers).** If the document already exists, its content will be synced, ignoring this value. Can be Plate JSON (`Value`), an HTML string, or a function returning/resolving to `Value`. If omitted or empty, a default empty paragraph is used for initialization if the Y.Doc is new. Whether to automatically call `provider.connect()` for all configured providers during initialization. Default: `true`. Set to `false` if you want to manage connections manually using `editor.api.yjs.connect()`. If set, automatically focuses the editor and places the cursor at the 'start' or 'end' of the document after initialization and sync. Specific Plate `Location` to set the selection to after initialization, overriding `autoSelect`. Resolves when the initial setup (including potential async `value` resolution and YjsEditor binding) is complete. Note that provider connection and synchronization happen asynchronously. ### `api.yjs.destroy` Disconnects all providers, cleans up Yjs bindings (detaches editor from Y.Doc), and destroys the awareness instance. **Must be called when the editor component unmounts** to prevent memory leaks and stale connections. ### `api.yjs.connect` Manually connects to providers. Useful if `autoConnect: false` was used during `init`. If provided, only connects to providers of the specified type(s). If omitted, connects to all configured providers that are not already connected. ### `api.yjs.disconnect` Manually disconnects from providers. If provided, only disconnects from providers of the specified type(s). If omitted, disconnects from all currently connected providers. 4d:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L4e",null,{"files":[{"path":"../../content/docs/(plugins)/(collaboration)/yjs.mdx","content":"$4f","type":"registry:file","target":"content/docs/plate/(plugins)/(collaboration)/yjs.mdx"}],"className":"h-[70svh] min-h-80"}]]}]