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.

Setup

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

$ npm install yorkie-js-sdk

After that, you can load the SDK by importing it in your JavaScript file:

1import yorkie from 'yorkie-js-sdk';

Alternatively, you can also include the following code in the <head> tag of your HTML:

<!-- Import yorkie-js-sdk -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/yorkie-js-sdk/0.3.5/yorkie-js-sdk.js"></script>
<script>
  // globally available as `yorkie` object
  const doc = new yorkie.Document('my-doc');
</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.todos = [];           // {"todos":[]}
3  root.todos.push('todo-1'); // {"todos":["todo-1"]}
4  root.obj = {               // {"todos":["todo-1"], "obj":{"name":"yorkie","age":14}}
5    name: 'yorkie',
6    age: 14,
7  };
8});

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.

The value can be: local-change, remote-change or snapshot.

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

To subscribe to changes for a specific path in the document, you can use the doc.subscribe(path, callback) with a path argument, such as $.todos, where the $ sign indicates the root of the document. The callback function is called when the target path and its nested values are changed.

With this feature, you can easily subscribe to changes for a specific part of the document and perform different actions based on the updated values.

1doc.subscribe('$.todos', (event) => {
2  // The callback will be called when the root.todos or its nested values change.
3  const target = doc.getValueByPath('$.todos'); // You can get the value by path.
4  // Do something...
5});

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    // get all clients connected to the Document.
4    // [ {clientID: string, presence: {key: value}}, ... ]
5    const peers = client.getPeersByDocKey(doc.getKey());
6    const peersCount = peers.length;
7    console.log(`There are currently ${peersCount} peers`);
8  }
9});

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