Plate yjs plugin

This package implements the yjs plugin for Plate with support for both Hocuspocus and WebRTC providers.

Documentation

Check out Collaboration for the main documentation.

Installation

This package only requires the providers you actually use. Each provider package is an optional dependency:

bash

# Base installation
npm install @platejs/yjs

# For Hocuspocus server-based collaboration
npm install @hocuspocus/provider

# For WebRTC peer-to-peer collaboration
npm install y-webrtc

# For IndexedDB persistence (optional)
npm install y-indexeddb

Provider Configuration

The plugin supports two types of providers out of the box, with full type safety:

Hocuspocus Provider
- Server-based collaboration using WebSocket
- Suitable for large-scale applications
- Requires a Hocuspocus server
WebRTC Provider
- Peer-to-peer collaboration using WebRTC
- No server required (except for signaling)
- Best for small to medium-sized groups

Configuration is done using the providerConfigs array with provider-specific type checking:

typescript

import { YjsPlugin } from '@platejs/yjs';
import * as Y from 'yjs';

// Create a Y.Doc (or use an existing one)
const ydoc = new Y.Doc();

const plugins = [
  // ... other plugins
  YjsPlugin({
    ydoc, // Pass your Y.Doc
    providerConfigs: [
      // Hocuspocus provider with type-checked options
      {
        type: 'hocuspocus',
        options: {
          url: 'ws://localhost:1234',
          name: 'document-name',
        },
      },
      // WebRTC provider with type-checked options
      {
        type: 'webrtc',
        options: {
          roomName: 'document-1',
          signaling: ['ws://127.0.0.1:4444'],
        },
      },
    ],
    // Optional: wait for all providers to sync before showing content
    waitForAllProviders: false, // Default is false
  }),
];

The configuration is fully type-safe, so you'll get autocomplete and type checking for provider-specific options.

Using Custom Providers (Like IndexedDB)

The plugin now supports passing in pre-instantiated providers that implement the UnifiedProvider interface. This is especially useful for:

Using providers that aren't built-in, like IndexedDB for offline persistence
Configuring providers with custom logic beyond what the built-in options support
Sharing provider instances across different parts of your application

Here's an example using IndexedDB for offline persistence:

typescript

import { YjsPlugin } from '@platejs/yjs';
import * as Y from 'yjs';
import { IndexeddbProvider } from 'y-indexeddb';
import { Awareness } from 'y-protocols/awareness';

// Create a Y.Doc
const ydoc = new Y.Doc();

// First, create the actual IndexedDB provider
const indexedDBInstance = new IndexeddbProvider('my-document', ydoc);

// Then wrap it to implement the UnifiedProvider interface
const indexedDBProvider = {
  // Required properties
  type: 'indexeddb',
  document: ydoc,
  awareness: new Awareness(ydoc),
  isConnected: true,
  isSynced: false,

  // Store the actual provider instance
  _provider: indexedDBInstance,

  // Required methods
  connect: function () {
    // IndexedDB is always "connected" locally
    this.isConnected = true;
    // Mark as synced once connected
    this.isSynced = true;
  },
  disconnect: function () {
    this.isConnected = false;
    this.isSynced = false;
  },
  destroy: function () {
    // Clean up the actual provider
    this._provider.destroy();
    this.disconnect();
  },
};

// Use your custom provider with the plugin
const plugins = [
  YjsPlugin({
    ydoc,
    // Pass your pre-instantiated providers
    customProviders: [indexedDBProvider],
    // You can still use built-in providers alongside custom ones
    providerConfigs: [
      {
        type: 'webrtc',
        options: {
          roomName: 'document-1',
        },
      },
    ],
  }),
];

The plugin will handle initializing, connecting, and synchronizing with all providers, regardless of whether they're built-in or custom. State tracking is maintained across all provider types.

Multiple Providers and Fallbacks

You can use multiple providers simultaneously with the same Y.Doc for different synchronization strategies:

typescript

import { YjsPlugin } from '@platejs/yjs';
import * as Y from 'yjs';

// Create a shared Y.Doc
const ydoc = new Y.Doc();

const plugins = [
  // ... other plugins
  YjsPlugin({
    ydoc,
    providerConfigs: [
      {
        type: 'webrtc',
        options: {
          roomName: 'document-1',
        },
      },
      {
        type: 'hocuspocus',
        options: {
          url: 'ws://localhost:1234',
          name: 'document-1',
        },
      },
    ],
    // Wait for all providers to sync before showing content
    waitForAllProviders: true,
  }),
];

How Multiple Providers Work Together

When you configure multiple providers:

All providers share the same Y.Doc instance
Data changes are automatically synced between all connected providers
If one provider (e.g., Hocuspocus server) goes down, other providers (e.g., WebRTC) continue to work
When a provider reconnects, it automatically syncs with the latest state
The plugin keeps track of how many providers are synced using a counter system

This lets you create robust setups like:

WebRTC for fast peer-to-peer editing with Hocuspocus for server persistence
Multiple Hocuspocus providers for fallback server connections
Custom IndexedDB provider for offline persistence
Any combination that suits your reliability and performance needs

By default, content will be shown as soon as at least one provider is synced. If waitForAllProviders is set to true, content will only appear when all configured providers are in sync.

Using Nested Y.Doc Structures

By default, the plugin uses ydoc.get('content', Y.XmlText) for storing editor content. However, you can use the sharedType option to work with nested structures from a parent Y.Doc:

typescript

import { YjsPlugin } from '@platejs/yjs';
import * as Y from 'yjs';

// Create a parent document with multiple nested editors
const parentDoc = new Y.Doc();

// Create nested structures for different editors
const editorsMap = parentDoc.getMap('editors');
const mainEditorContent = new Y.XmlText();
const sidebarEditorContent = new Y.XmlText();

// Store them in the parent doc
editorsMap.set('main', mainEditorContent);
editorsMap.set('sidebar', sidebarEditorContent);

// You can also store other data in the parent doc
const metadata = parentDoc.getMap('metadata');
metadata.set('title', 'My Document');
metadata.set('author', 'John Doe');
metadata.set('createdAt', Date.now());

// Create the main editor with the nested shared type
const mainEditor = createPlateEditor({
  plugins: [
    YjsPlugin.configure({
      ydoc: parentDoc, // Pass the parent doc for provider sync
      sharedType: mainEditorContent, // Use the specific nested content
      providers: [
        {
          type: 'webrtc',
          options: { roomName: 'my-document' },
        },
      ],
    }),
  ],
});

// Create a sidebar editor with its own nested shared type
const sidebarEditor = createPlateEditor({
  plugins: [
    YjsPlugin.configure({
      ydoc: parentDoc, // Same parent doc
      sharedType: sidebarEditorContent, // Different nested content
      providers: [], // Don't create new providers, parent is already synced
    }),
  ],
});

// Initialize with initial values - they'll be applied to the correct sharedTypes
await mainEditor.api.yjs.init({
  autoConnect: true,
  value: [{ type: 'p', children: [{ text: 'Main editor content' }] }],
});
await sidebarEditor.api.yjs.init({
  autoConnect: false,
  value: [{ type: 'p', children: [{ text: 'Sidebar content' }] }],
});

Important: When using a custom sharedType, the initial value passed to init() will be applied directly to that specific sharedType, not to the default ydoc.get('content', Y.XmlText). This ensures each editor's initial content goes to the correct location in your nested structure.

Cursor Support

Collaborative cursors are enabled by default. You can customize their appearance and behavior:

typescript

YjsPlugin({
  ydoc,
  providerConfigs: [/* providers */],
  cursorOptions: {
    // Custom cursor options
    cursorData: {
      name: 'User Name',
      color: '#f00',
    },
  },
  // Alternatively, set disableCursors: true to disable cursors completely
}),

Custom Provider Registration

For more complex scenarios, you can register your own provider types for the plugin to create automatically:

typescript

import { registerProviderType } from '@platejs/yjs';
import * as Y from 'yjs';
import { Awareness } from 'y-protocols/awareness';
import { ProviderEventHandlers } from '@platejs/yjs';

// Create a custom provider class that implements UnifiedProvider interface
class CustomProviderWrapper {
  type = 'custom';
  private _awareness: Awareness;
  private _document: Y.Doc;
  private _isConnected = false;
  private _isSynced = false;
  private handlers?: ProviderEventHandlers;

  constructor(options, handlers, ydoc, awareness) {
    this.handlers = handlers;
    this._document = ydoc || new Y.Doc();
    this._awareness = awareness || new Awareness(this._document);
    // Setup your provider using the options...
  }

  // Required methods from UnifiedProvider interface
  connect() {
    // Implementation that connects to your service
    this._isConnected = true;
    // When you connect and become synced:
    this._isSynced = true;
    this.handlers?.onSyncChange?.(true);
  }

  disconnect() {
    // Implementation to disconnect
    this._isConnected = false;

    // If we were synced, report sync state change
    if (this._isSynced) {
      this._isSynced = false;
      this.handlers?.onSyncChange?.(false);
    }
  }

  destroy() {
    // Clean up resources
    this.disconnect();
  }

  get awareness() {
    return this._awareness;
  }

  get document() {
    return this._document;
  }

  get isConnected() {
    return this._isConnected;
  }

  get isSynced() {
    return this._isSynced;
  }
}

// Register your custom provider type
registerProviderType('custom', CustomProviderWrapper);

// Then use it in your config just like built-in providers
YjsPlugin({
  ydoc,
  providerConfigs: [
    {
      type: 'custom', // Use your registered type
      options: {
        // Custom options for your provider
      },
    },
  ],
});

Note: There are two ways to use custom providers:

Use customProviders to pass pre-instantiated provider objects (simpler for one-off usage)

Use registerProviderType to register a provider class that can be created via providerConfigs (better for reusable providers)

License

MIT