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:

Having trouble? Get in touch with us on Gitter!

Prepare your environment

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

Copied to clipboard!
mkdir kuzzle-playground
cd kuzzle-playground
npm install kuzzle-sdk

If you are performing a clean install you might see some UNMET PEER DEPENDENCY warnings, these are safe to ignore as they refer to optional dependencies.

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:

Copied to clipboard!
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.

Copied to clipboard!


 

 
 
 
 




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:

Copied to clipboard!
// 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

Copied to clipboard!
node first-step.js

Your console should output the following message:

Copied to clipboard!
playground/mycollection ready

Congratulations! You are now ready to say Hello to the World!

Create your first "Hello World" document

Create a create.js file with the following code:

Copied to clipboard!
// 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

Copied to clipboard!
node create.js

Your console should show the following message:

Copied to clipboard!
document created

You have now successfully stored your first document into Kuzzle. Check the Admin Console Guide to see how to browse your collection and confirm that your document was saved.

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:

Copied to clipboard!
// 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

Copied to clipboard!
node create.js

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

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

Congratulations! You have just choreographed your first pub/sub pattern!

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)