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.

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 #

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

npm install kuzzle-sdk

Then, create a init-kuzzle.js file and start by adding the code below. This will load the Kuzzle Javascript SDK:

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.

const kuzzle = new Kuzzle(new WebSocket('kuzzle'));

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

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.

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.

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:

// 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.

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

Your console should output the following message:

nyc-open-data/yellow-taxi ready!

Create your first document #

Create a create.js file with following code:

// 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

<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

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:

New document successfully created!

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:

// 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

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:

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.

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 Reference
• learn how to use Koncorde to create incredibly fine-grained and blazing-fast subscriptions
• follow our guide to learn how to implement basic authentication
• follow our guide to learn how to implement manage users and setup fine-grained access control