Collaboration - Plate

Installation

Install the Yjs plugin.

pnpm add @platejs/yjs

pnpm add @platejs/yjs

For Hocuspocus server-based collaboration:

pnpm add @hocuspocus/provider

pnpm add @hocuspocus/provider

For WebRTC peer-to-peer collaboration:

pnpm add y-webrtc

pnpm add y-webrtc

Add The Plugin

Every peer in a room must use the same compiled schema identity. Derived schemas match by fingerprint. Use an explicit id and version for a durable room lineage, and migrate the room before bumping the version.

import { YjsPlugin } from "@platejs/yjs/plate";
import { createPlateEditor } from "platejs/react";
 
const editor = createPlateEditor({
  schema: { id: "yjs-example", version: 1 },
  plugins: [
    YjsPlugin.configure({
      initialState: {
        clientId: "local-user",
        doc,
        provider,
        rootName: roomId,
      },
    }),
  ],
  initialValue,
});

Provider Boundary

App code owns the provider package, room name, authentication, persistence, and server scaling. YjsPlugin owns Plate composition and installs the Plite/Yjs synchronization extension.

Configure Provider And Cursors

Wrap your provider as YjsProviderLike, then pass it through the plugin's initialState. The Plate subpath exports the plugin; the React subpath exports remote cursor hooks.

import { YjsPlugin } from "@platejs/yjs/plate";
import { useYjsRemoteCursors } from "@platejs/yjs/react";
import { RemoteCursorOverlay } from "@/components/editor/remote-cursor-overlay";
 
export const yjsPlugin = YjsPlugin.configure({
  initialState: {
    clientId: user.id,
    doc,
    provider,
    rootName: roomId,
  },
});

import { YjsPlugin } from

provider: A YjsProviderLike wrapper around app-owned transport code.
doc: The shared Y.Doc.
rootName: The collaboration document namespace. Its primary and named roots synchronize together.
Standalone collab: "shared" effect descriptors belong to installed editor extensions. YjsPlugin discovers them from the editor.
Cursor data is sent through tx.yjs.sendSelection(...) when the local selection changes.

One Plate commit that changes primary and named roots becomes one Yjs transaction. Plite History records that editor commit as one history batch. Named roots synchronize without a mounted PlateContent, and remote selections preserve their root key. A selection cannot span two roots.

Add Editor Container

The RemoteCursorOverlay requires a positioned container around the editor content. Use EditorContainer component or PlateContainer from platejs/react:

import { Plate } from "platejs/react";
import { EditorContainer } from "@/components/editor/editor";
 
return (
  <Plate editor={editor}>
    <EditorContainer>
      <Editor />
    </EditorContainer>
  </Plate>
);

import { Plate } from "platejs/react";
import { EditorContainer } from

Read And Control Connection State

The plugin installs a yjs group in editor.read and editor.update.

const connected = editor.read((state) => state.yjs.connected());
const providerStatus = editor.read((state) => state.yjs.providerStatus());
 
editor.update((tx) => {
  tx.yjs.connect();
  tx.yjs.sendSelection(selection, { name: "Ada", color: "#aabbcc" });
});

The installed extension cleanup destroys editor-owned listeners. Provider destruction depends on whether the provider wrapper declares itself editor-owned.

Monitor Connection Status (Optional)

Access provider states and add event handlers for connection monitoring:

import React from "react";
import { useYjsProviderStatus, useYjsProviderSynced } from "@platejs/yjs/react";
 
function EditorStatus() {
  const status = useYjsProviderStatus(editor);
  const synced = useYjsProviderSynced(editor);
 
  return (
    <div>
      {status} {synced ? "Synced" : "Syncing"}
    </div>
  );
}

Concern	Owner
`Y.Doc` and root name	App plus `YjsPlugin` config
Provider package installation	App
Room naming and authentication	App
Persistence and server scaling	App
Editor operations, selection, undo/redo	`@platejs/plite` and `@platejs/plite-history`
Awareness and remote cursors	`@platejs/yjs`

const connected = editor.read((state) => state.yjs.connected());
const synced = editor.read((state) => state.yjs.providerSynced());
 
editor.update((tx) => {
  tx.yjs.connect();
  tx.yjs.sendSelection(selection, { name: "Ada", color: "#aabbcc" });
});

const connected = editor.read((state) => state.yjs.connected());
const synced = editor.read((state) => state.yjs.providerSynced());
 
editor.update((tx) => {
  tx.yjs.connect();
  tx.yjs.sendSelection(selection, { name: "Ada", color: "#aabbcc" });
});

Command	Use
`tx.yjs.connect()`	Connect the provider.
`tx.yjs.disconnect()`	Disconnect without tearing down the editor.
`tx.yjs.reconnect()`	Reconnect after a provider interruption.
`tx.yjs.sendSelection(range, data)`	Publish local selection and cursor metadata.
`tx.yjs.clearSelection()`	Clear local awareness selection.

import { YjsPlugin } from "@platejs/yjs/plate";
import { createPlateEditor } from "platejs/react";
 
const editor = createPlateEditor({
  schema: { id: "yjs-example", version: 1 },
  plugins: [
    YjsPlugin.configure({
      initialState: {
        clientId: "local-user",
        doc,
        provider,
        rootName: roomId,
      },
    }),
  ],
  initialValue,
});

import React from "react";
import { useYjsProviderStatus, useYjsProviderSynced } from "@platejs/yjs/react";
 
function EditorStatus() {
  const status = useYjsProviderStatus(editor);
  const synced = useYjsProviderSynced(editor);
 
  return (
    <div>
      {status} {synced ? "Synced" : "Syncing"}
    </div>
  );
}