Yorkie

Getting Started with JS SDK

Let's start using Yorkie with the JS SDK. You need an environment that can run JavaScript, such as a browser.

Installation

To use the Yorkie JavaScript SDK in your project, you will need to install it using npm:

$ npm install yorkie-js-sdk

or just include the following code in the <head> tag of your HTML:

<!-- include yorkie js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/yorkie-js-sdk/0.2.20/yorkie-js-sdk.js"></script>

The JS SDKs are also provided by cdnjs to make loading library files faster and easier on websites.
For more the JS SDKs: https://cdnjs.com/libraries/yorkie-js-sdk

How to use Yorkie

1. Creating a Client with API key

First, create a Client with API key.

1async function main() {
2  // 01. create a new client instance and connect to the yorkie server.
3  const client = new yorkie.Client('https://api.yorkie.dev', {
4    apiKey: 'xxxxxxxxxxxxxxxxxxxx',
5  });
6  await client.activate();
7

8  // ...
9}

The API key is used to identify the project in Yorkie. You can get the API key of the project you created in the Dashboard.

2. Creating a Document

Then create a Document.

1// 02. create a new document and attach it to the client
2const doc = new yorkie.Document('my-doc');
3await client.attach(doc);

The created document should be attached to the client to automatically synchronize the document between the client and peers.

3. Updating the Document

The created document is initially an empty object. You can create or update a key-value property you would like to share with peers using doc.update().

1doc.update((root) => {
2  root['key'] = 'value'; // {"key":"value"}
3});

4. Accessing Document

If you want to access the document properties, you can use doc.getRoot(). Using a dot notation, you can access a key-value property you or your peers have set.

1doc.update((root) => {
2  root.sharedMessage = 'Hello World!';
3});
4console.log(doc.getRoot().sharedMessage); // "Hello World!";

5. Subscribing to the changes that happen in the Document

Clients sharing the same document can subscribe to the changes that happen in the Document using doc.subscribe()

1doc.subscribe((event) => {
2  console.log('A change event occurred in the Document!');
3});

You can execute different actions depending on the source of change. The source can be accessed from event.type.

1doc.subscribe((event) => {
2  if (event.type === 'remote-change') {
3    console.log('A peer has changed the Document!');
4  }
5});

Accessing certain document properties when a specific property in the document is changed is the key to creating a collaborative application. You can perform different actions based on which property has changed in the document by examining paths array that exists in event.value array.

1doc.subscribe((event) => {
2 if (event.type === 'remote-change') {
3    for (const changeInfo of event.value) {
4      for (const path of changeInfo.paths) {
5        if (path.startsWith('$.sharedMessage') {
6          console.log(`One of your peers has changed the message to ${doc.getRoot().sharedMessage}`)
7        }
8      }
9    }
10  }
11});

6. Viewing the presence of other peers

Other peers' activities can be accessed by subscribing to the client.

1client.subscribe((event) => {
2  if (event.type === 'peers-changed') {
3    const peers = event.value[doc.getKey()];
4    const peersCount = Object.entries(peers).length;
5    console.log(`There are currently ${peersCount} peers`);
6  }
7});

Next, let's take a look at the JS SDK.