@wordpress/sync

Sync entity data between peers for real-time collaboration using CRDT documents.

This package provides the syncing layer for real-time collaboration in the WordPress editor. It is built on Yjs, a CRDT implementation that enables multiple users to edit shared data concurrently without conflicts.

See CODE.md for architecture details.

Installation

Install the module

npm install @wordpress/sync --save

API

Awareness

The Awareness protocol should not be considered a public API. It is a third-party library that will experience breaking changes in the future.

In general, awareness for core entity types is implemented by the core-data package and third-party Yjs providers should not provide their own awareness implementation. However, it may be desirable for custom entities to have a custom awareness implementation.

privateApis

Private @wordpress/sync APIs.

Y

Yjs should not be considered a public API. It is a third-party library that will experience breaking changes in the future.

Two Yjs instances operating on the same document cause silent data corruption:

https://github.com/yjs/yjs/issues/438

For that reason, sync providers registered via the sync.providers filter must not bundle their own copy of Yjs. Each provider creator receives the Yjs module used by the editor as the Y property of its options, alongside ydoc and awareness, and must operate on documents through that instance.

A provider that bundles third-party code importing yjs directly (for example y-websocket) can share the editor’s Yjs instance through a shim module. The shim re-exports the Yjs symbols the bundled code uses and fills them in at runtime from the Y option:

// yjs-shim.js
export let Doc;
export let applyUpdate;
export let encodeStateAsUpdate;
export let encodeStateVector;

export function setYjsModule( Y ) {
    ( { Doc, applyUpdate, encodeStateAsUpdate, encodeStateVector } = Y );
}

The build then aliases the yjs module specifier to the shim, so bundled dependencies resolve their Yjs imports to it instead of packaging a second copy. For example, with webpack:

resolve: {
  alias: {
    yjs: path.resolve( __dirname, 'src/yjs-shim.js' ),
  },
},

Finally, the provider creator initializes the shim before using any of the bundled code:

import { WebsocketProvider } from 'y-websocket';
import { setYjsModule } from './yjs-shim';

const createProvider = async ( { awareness, ydoc, Y } ) => {
    setYjsModule( Y );

    const provider = new WebsocketProvider( url, room, ydoc, { awareness } );
    // ...
};

See packages/e2e-tests/plugins/rtc-websocket-provider for a complete working example.

Deprecated: @wordpress/sync is currently also exposed as the wp-sync WordPress script, which provides the same Yjs module as the wp.sync.Y global. This global will be removed in a future release, and it is already unavailable in WordPress core. Providers that still resolve yjs to wp.sync.Y through webpack externals should migrate to the Y option described above.

YJS_VERSION

The major version of Yjs that is bundled and exported by this package. This can be used by third-party code to ensure that they are targeting a compatible version of Yjs.

Contributing to this package

This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.