First Steps with Kuzzle #

It's time to play with the Kuzzle JS SDK. In this section, we will learn how to store a document and subscribe to notifications in Kuzzle using the Javascript SDK in a simple NodeJS client application.

Before proceeding, please make sure your system has these programs installed:

• Node.js version 6 or higher (download page)
• Kuzzle

Prepare your environment #

Create your playground directory and install the Javascript SDK from the command line using npm:

mkdir kuzzle-playground
cd kuzzle-playground
npm install kuzzle-sdk

Then, create an init.js file and start by loading the Kuzzle Javascript SDK. Next, instantiate a client that automatically connects to Kuzzle via WebSocket. Replace 'kuzzle' with the corresponding server name or IP address:

const {
  Kuzzle,
  WebSocket
} = require('kuzzle-sdk');
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));

Finally, we will add the code that will access Kuzzle to create a new index 'playground' and a new collection 'mycollection' that we will use to store data later on.

try {
  // Create a 'playground' index
  await kuzzle.index.create('playground');
  // Create a collection named 'mycollection' in playground index
  await kuzzle.collection.create(
    'playground',
    'mycollection'
  );
  console.log('playground/mycollection ready');
} catch (error) {
  console.error(error.message);
}

Your first-step.js file should now look like this:

// Load the Kuzzle SDK module
const {
  Kuzzle,
  WebSocket
} = require('kuzzle-sdk');
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
const run = async () => {
  try {
    await kuzzle.connect();
    // Create a 'playground' index
    await kuzzle.index.create('playground');
    // Create a collection named 'mycollection' in playground index
    await kuzzle.collection.create(
      'playground',
      'mycollection'
    );
    console.log('playground/mycollection ready');
  } catch (error) {
    console.error(error.message);
  } finally {
    kuzzle.disconnect();
  }
};
run();

This code does the following:

• loads the Kuzzle SDK from its NPM package
• creates an instance of the SDK and connects it to Kuzzle running on localhost (and selects the playground as default index),
• creates the playground index,
• creates the mycollection collection (within the playground index),
• disconnects from Kuzzle after the collection is created or if an error occurs.

Run your file in Node.js

node first-step.js

Your console should output the following message:

playground/mycollection ready

Create your first "Hello World" document #

Create a create.js file with the following code:

// load the Kuzzle SDK module
const {
  Kuzzle,
  WebSocket
} = require('kuzzle-sdk');
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
const message = {message: 'Hello, World!'};
const run = async () => {
  try {
    await kuzzle.connect();
    await kuzzle.document.create(
      'playground',
      'mycollection',
      message
    );
    console.log('document created');
  } catch (error) {
    console.error(error.message);
  } finally {
    kuzzle.disconnect();
  }
};
run();

This code does the following:

• creates a new document containing the message "Hello, World" in mycollection within the playground index,
• logs a success message to the console if everything went fine,
• logs an error message if any of the previous actions failed,
• disconnects from Kuzzle after the document is created or if an error occurs.

Run your file in Node.js

node create.js

Your console should show the following message:

document created

You can find more resources about Kuzzle SDK in the SDK Reference.

Subscribe to data changes (pub/sub) #

Kuzzle provides pub/sub features that can be used to trigger real-time notifications based on the state of your data (for a deep-dive on notifications check out the Room class definition in the [/sdk](SDK Reference)).

Let's get started. Complete your create.js file:

// Load the Kuzzle SDK module
const {
  Kuzzle,
  WebSocket
} = require('kuzzle-sdk');
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
const message = {message: 'Hello, World!'};
// Define a filter
const filter = {exists: {field: 'message'}};
// Will be called each time a document match the filter
const callback = notifications => {
  console.log(
    'message received from kuzzle',
    notifications.result._source.message
  );
};
const run = async () => {
  try {
    await kuzzle.connect();
    // Create a subscription on the collection matching given filters
    await kuzzle.realtime.subscribe(
      'playground',
      'mycollection',
      filter,
      callback
    );
    await kuzzle.document.create(
      'playground',
      'mycollection',
      message
    );
  } catch (error) {
    console.error(error.message);
  } finally {
    kuzzle.disconnect();
  }
};
run();

Run your file in Node.js

node create.js

This creates a new document in Kuzzle, triggering a notification:

subscribe ok
document created
message received from kuzzle: Hello, World!

Where do we go from here? #

Now that you're more familiar with Kuzzle, dive even deeper to learn how to leverage its full capabilities:

• take a look at the [/sdk](SDK Reference)
• learn how to use /core/1/guides/cookbooks/realtime-api to create incredibly fine-grained and blazing-fast subscriptions
• follow our guide to learn how to implement [/core/1/guides/essentials/user-authentication#local-strategy](basic authentication)
• follow our guide to learn how to implement [/core/1/guides/essentials/security/](manage users and setup fine-grained access control)