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.

ConnectionErrorCode

Error codes reported by a sync provider when its connection fails.

CRDT_DOC_META_PERSISTENCE_KEY

Key of the in-memory meta entry marking a CRDT document as loaded from persistence. It is not synced or persisted.

CRDT_RECORD_MAP_KEY

Root-level key for the map that holds the entity record data.

createSyncManager

Creates the sync manager, which orchestrates the lifecycle of syncing entity records: it creates Yjs documents, connects to providers, creates awareness instances, and coordinates with the core-data store. Exported for @wordpress/core-data; plugins don't need it.

Delta

Quill Delta implementation used to describe rich text changes.

LOCAL_EDITOR_ORIGIN

Origin string for CRDT document changes originating from the local editor.

LOCAL_UNDO_IGNORED_ORIGIN

Origin string for CRDT document changes that should be synced but not recorded in the undo history (e.g. status changes during publish).

retrySyncConnection

Retries the HTTP polling connection now instead of waiting for the next automatic retry. Exported for @wordpress/core-data; plugins don't need it.

Y

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

@wordpress/sync is a bundled package: each consumer bundles its own copy, and no wp.sync global or wp-sync script handle is exposed by WordPress. 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.

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.