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();78 // ...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 client2const 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.