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://cdn.jsdelivr.net/npm/@yorkie-js/sdk@0.6.18/dist/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 jsdelivr to make loading library files faster and easier on websites.
For more the JS SDKs: https://www.jsdelivr.com/package/npm/@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({
4    rpcAddr: 'https://api.yorkie.dev',
5    apiKey: 'xxxxxxxxxxxxxxxxxxxx',
6  });
7  await client.activate();
8

9  // ...
10}

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, { initialPresence: {} });

The document should be attached to the client in order to automatically synchronize it between the users participating the document.

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});

6. Viewing the presence of users

You can also subscribe to the presence of users participating in the document using doc.subscribe('presence'). You can use doc.getPresences() to get the list of users who are currently involved in the document.

1doc.subscribe('presence', (event) => {
2  // get all users connected to the Document.
3  const users = doc.getPresences(); // [ {clientID: string, presence: {key: value}}, ... ]
4  console.log(`There are currently ${users.length} users online`);
5});

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