SDK
SDK Javascript v6.x
1

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

Getting Started with Kuzzle and Webpack #

In this tutorial you will learn how to install, run and use Kuzzle with the Javascript SDK in the browser using Webpack. We will walk you through creating scripts that can store documents in Kuzzle and subscribe to notifications for each new document created.

Having trouble? Get in touch with us on Discord!

Running Kuzzle #

Before going through this tutorial, you should have a Kuzzle server running. Please refer to the Running Kuzzle Tutorial if you don't have one yet.

Fun with the SDK #

It's time to play with the Kuzzle Javscript SDK. In this section, we will store a document and subscribe to notifications in Kuzzle using the Javascript SDK in your browser.

Before proceeding, please make sure your system has Node.js version 8 or higher (instructions here) installed.

Including the Kuzzle SDK in a Webpack project #

This section explains how to use the Kuzzle SDK within an existing Webpack project. If you don't have your project up and running yet and want to learn how to leverage Webpack to build it, please refer to the official Webpack Getting Started page.

In your terminal, go to the root of your front-end project using Webpack and type

Copied to clipboard!
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 a init-kuzzle.js file and start by adding the code below. This will load the Kuzzle Javascript SDK:

Copied to clipboard!
import { Kuzzle, WebSocket } from 'kuzzle-sdk';

Next, we instantiate a client that will connect to Kuzzle via WebSocket. If Kuzzle is not running on localhost, replace it with the corresponding server name or IP address.

Copied to clipboard!
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));

Next we add a listener to be notified in case of a connection error:

Copied to clipboard!
kuzzle.on('networkError', error => {
  console.error(`Network Error: ${error}`);
});

Then we have to connect our web app to the Kuzzle server with the connect() method.

Copied to clipboard!
const run = async () => {
  try {
    // Connect to Kuzzle server
    await kuzzle.connect();
    // Some more things will go here...
  } catch (error) {
    console.error(error.message);
  } finally {
    kuzzle.disconnect();
  }
};

Finally, we will create a new index nyc-open-data and a new collection yellow-taxi that we will use to store data later on.

Copied to clipboard!
const run = async () => {
  try {
    // Connect to Kuzzle server
    await kuzzle.connect();
    // Create an index
    await kuzzle.index.create('nyc-open-data');
    // Create a collection
    await kuzzle.collection.create('nyc-open-data', 'yellow-taxi');
    console.log('nyc-open-data/yellow-taxi ready!');
  } catch (error) {
    console.error(error.message);
  } finally {
    kuzzle.disconnect();
  }
};

Your kuzzle-init.js file should now look like this:

Copied to clipboard!
// load the Kuzzle SDK module
import { Kuzzle, WebSocket } from 'kuzzle-sdk';
// instantiate a Kuzzle client
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
// add a listener to detect any connection problems
kuzzle.on('networkError', error => {
  console.error(`Network Error: ${error}`);
});
const run = async () => {
  try {
    // Connect to Kuzzle server
    await kuzzle.connect();
    // Create an index
    await kuzzle.index.create('nyc-open-data');
    // Create a collection
    await kuzzle.collection.create('nyc-open-data', 'yellow-taxi');
    console.log('nyc-open-data/yellow-taxi 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
  • connects it to Kuzzle running on localhost with the WebSocket protocol
  • creates the nyc-open-data index
  • creates the yellow-taxi collection (within the nyc-open-data index),
  • disconnects from Kuzzle after the collection is created or if an error occurs

Now, to have your script up and running, require it somewhere in your application (e.g. your main entry point) and launch it.

Copied to clipboard!
require('../path/to/init-kuzzle.js');

Your console should output the following message:

Copied to clipboard!
nyc-open-data/yellow-taxi ready!

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

Having trouble? Get in touch with us on Discord! We're happy to help.

Create your first document #

Create a create.js file with following code:

Copied to clipboard!
// load the Kuzzle SDK module
import { Kuzzle, WebSocket } from 'kuzzle-sdk';
// instantiate a Kuzzle client
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
// add a listener to detect any connection problems
kuzzle.on('networkError', error => {
  console.error(`Network Error: ${error}`);
});
const doIt = async () => {
  try {
    // Connect to Kuzzle server
    await kuzzle.connect();
    // Create your document
    const driver = {
      name: 'Sirkis',
      birthday: '1959-06-22',
      license: 'B'
    };
    await kuzzle.document.create('nyc-open-data', 'yellow-taxi', driver);
    console.log('New document successfully created!');
  } catch (error) {
    console.error(error.message);
  } finally {
    kuzzle.disconnect();
  }
};
export default doIt;

This code does the following:

  • creates a new document in nyc-open-data within the yellow-taxi 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

To activate this code, create a button somewhere in your page like the following

Copied to clipboard!
<button type="button" id="create-document-btn">
  Crate a new document in Kuzzle
</button>

Then, associate it to the create function by adding this code to your application

Copied to clipboard!
const create = require('../path/to/create.js');

// This is the most "vanilla" way to call a function in reaction to a click,
// if you're using a front-end framework like Vuejs, React or jQuery, feel free
// to follow any convenience method it provides for this purpose.
document.querySelector('#create-document-btn').addListener('click', event => {
  create();
});

Now, click the button and check your console for a message like the following:

Copied to clipboard!
New document successfully created!

You have now successfully stored your first document into Kuzzle. Click here to see how you can use the Kuzzle Admin Console to browse your collection and confirm that your document was saved.

Having trouble? Get in touch with us on Discord! We're happy to help.

Subscribe to realtime document notifications (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 realtime notifications documentation).

Let's get started. Create a subscribe.js file with following code:

Copied to clipboard!
// load the Kuzzle SDK module
import { Kuzzle, WebSocket } from 'kuzzle-sdk';
// instantiate a Kuzzle client
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
// add a listener to detect any connection problems
kuzzle.on('networkError', error => {
  console.error(`Network Error: ${error}`);
});
const doIt = async () => {
  try {
    // Connect to Kuzzle server
    await kuzzle.connect();
    // Define a filter
    const filter = {
      equals: { license: 'B' }
    };
    // Define a callback
    const callback = notification => {
      if (
        notification.type === 'document' &&
        notification.action === 'create'
      ) {
        const driver = notification.result._source;
        const driverId = notification.result._id;
        console.log(
          `New driver ${driver.name} with id ${driverId} has B license.`
        );
      }
    };
    // Subscribes to document notifications with our filter
    await kuzzle.realtime.subscribe(
      'nyc-open-data',
      'yellow-taxi',
      filter,
      callback
    );
    console.log('Successfully subscribed to document notifications!');
  } catch (error) {
    console.error(error.message);
  }
};
doIt();

This code does the following:

  • loads the Kuzzle SDK from its NPM package
  • creates an instance of the SDK
  • connects it to Kuzzle running on localhost with the websocket protocol
  • defines a filter for the subscription to be done later (drivers with "B" license)
  • defines a callback that will be called whenever a notification is received from Kuzzle (print driver name to console)
  • subscribes for notifications on the yellow-taxi collection

You can execute this code in the same page as before or in another page of your app. Whatever option you choose, to execute the code, you just need to require it in your page

Copied to clipboard!
require('../path/to/subscribe.js');

From now on, whenever you click the button we created before, Kuzzle will send a notification to the page containing the subscription to the yellow-taxi collection. In the console corresponding to this page, you should see the following message:

Copied to clipboard!
New driver Sirkis with id <driver-id> has B license.

In place of <driver-id> you'll see the ID that Kuzzle automatically generated for the document.

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

Having trouble? Get in touch with us on Discord! We're happy to help.

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: