Yorkie

If you want to update this page or add new content, please submit a pull request to the Homepage.

Getting Started with JS SDK

This guide walks you through setting up 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, 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.48/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: {} });

Attach the document to the client to automatically synchronize it between users participating in the document.

3. Updating the Document

The document is initially an empty object. You can create or update key-value properties 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

To access document properties, use doc.getRoot(). With dot notation, you can access any key-value property that 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 changes 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 user presence using doc.subscribe('presence'). Use doc.getPresences() to get the list of users currently participating 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.