Sync data between multiple peers and persist in a local database.
Installation
Install the module
npm install @wordpress/sync --save
API
Awareness
Similar to Yjs, 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. However, in order to allow third-party plugins to provide their own Yjs providers / sync transport, they must import and consume our instance of Yjs due to this bug / feature:
In other words, external code must be able to import Yjs from the @wordpress/sync package in their code, e.g.:
import { Y } from '@wordpress/sync';
Additionally, this import must resolve to wp.sync via DependencyExtractionWebpackPlugin. If you are using an older version of @wordpress/scripts that does not treat @wordpress/sync as an unbundled package, then you can use Webpack externals to manually resolve the package to the global wp.sync variable:
externals: {
...existingConfig.externals,
// Resolve @wordpress/sync to the global `wp.sync` provided by WordPress.
'@wordpress/sync': 'wp.sync',
// Resolve Yjs to the global `wp.sync.Y` provided by the sync package.
// Since dependencies import 'yjs' directly, we need to avoid importing
// and packaging two different Yjs instances, which would result in this
// conflict:
//
// https://github.com/yjs/yjs/issues/438
yjs: 'wp.sync.Y',
},
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.