Title: @wordpress/sync
Published: August 9, 2023
Last modified: October 9, 2026

---

# @wordpress/sync

## In this article

 * [Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#installation)
 * [API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#api)
    - [Awareness](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#awareness)
    - [ConnectionErrorCode](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#connectionerrorcode)
    - [CRDT_DOC_META_PERSISTENCE_KEY](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#crdt_doc_meta_persistence_key)
    - [CRDT_RECORD_MAP_KEY](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#crdt_record_map_key)
    - [createSyncManager](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#createsyncmanager)
    - [Delta](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#delta)
    - [LOCAL_EDITOR_ORIGIN](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#local_editor_origin)
    - [LOCAL_UNDO_IGNORED_ORIGIN](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#local_undo_ignored_origin)
    - [retrySyncConnection](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#retrysyncconnection)
    - [Y](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#y)
    - [YJS_VERSION](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#yjs_version)
 * [Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#contributing-to-this-package)

[ Back to top](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#wp--skip-link--target)

Sync entity data between peers for real-time collaboration using [CRDT](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type)
documents.

This package provides the syncing layer for real-time collaboration in the WordPress
editor. It is built on [Yjs](https://docs.yjs.dev/), a CRDT implementation that 
enables multiple users to edit shared data concurrently without conflicts.

See [CODE.md](https://github.com/WordPress/gutenberg/tree/HEAD/packages/sync/CODE.md)
for architecture details.

## 󠀁[Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#installation)󠁿

Install the module

    ```bash
    npm install @wordpress/sync --save
    ```

## 󠀁[API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#api)󠁿

### 󠀁[Awareness](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#connectionerrorcode)󠁿

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

### 󠀁[CRDT_DOC_META_PERSISTENCE_KEY](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#crdt_record_map_key)󠁿

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

### 󠀁[createSyncManager](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#delta)󠁿

Quill Delta implementation used to describe rich text changes.

### 󠀁[LOCAL_EDITOR_ORIGIN](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#local_editor_origin)󠁿

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

### 󠀁[LOCAL_UNDO_IGNORED_ORIGIN](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#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](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:

    ```typescript
    // 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:

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

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

    ```typescript
    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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-sync/?output_format=md#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](https://www.npmjs.com/)
and used by [WordPress](https://make.wordpress.org/core/) 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](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

First published

August 9, 2023

Last updated

October 9, 2026

Edit article

[ Improve it on GitHub: @wordpress/sync ](https://github.com/WordPress/gutenberg/edit/trunk/packages/sync/README.md)

[  Previous: @wordpress/stylelint-config](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-stylelint-config/)

[  Next: @wordpress/theme](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-theme/)