Getting Started with Kuzzle in the browser #

This tutorial explains how to use Kuzzle with the Javascript SDK in a browser.

To follow this tutorial, you must have a Kuzzle Server up and running (you'll need to know the hostname of the machine running it). If this is not already the case, take a look at how to run Kuzzle.

Before proceeding, make sure your system has Node.js version 8 or higher (download page) installed.

In this tutorial, you'll learn how to store a document and subscribe to notifications in Kuzzle using the Javascript SDK.

Having trouble? Get in touch with us on Discord!

Prepare your environment #

Create your playground directory:

mkdir "kuzzle-playground"
cd "kuzzle-playground"

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

Then, create an index.html file with the following structure:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <title>Kuzzle SDK Playground</title>

    <!-- If you are coding for Internet Explorer, please uncomment the following line -->
    <!-- <script src="//cdn.jsdelivr.net/npm/bluebird@3.5.3/js/browser/bluebird.min.js"></script> -->

    <script src="https://cdn.jsdelivr.net/npm/kuzzle-sdk/dist/kuzzle.min.js"></script>
  </head>
  <body></body>
</html>

If you are using Internet Explorer (not Edge), you are responsible of installing a Promise polyfill, which enables IE to support Javascript Promises.
Our advice is to use Bluebird, as shown in the code example above (refer to the commented lines in the head tag).

Then, add the code below in the body tag. This loads the SDK and connects it to a Kuzzle instance using the WebSocket protocol. If an error occurs, it is displayed in the console. Once the connection is established, a success message is displayed in the console.

<script>
  var kuzzle = new KuzzleSDK.Kuzzle(
    new KuzzleSDK.WebSocket('kuzzle')
  );
  kuzzle.on('networkError', error => {
    console.error('Network Error: ', error);
  });
  kuzzle.on('connected', () => {
    console.log('Successfully connected to Kuzzle');
  });
  kuzzle.connect();
</script>

Replace kuzzle with localhost or with the host name where your Kuzzle server is running.

Now you have to add the code that will access Kuzzle to create a new index nyc-open-data and a new collection yellow-taxi that you will use to store data later on. Make sure the code inside your body tag looks like the following:

<script>
  var kuzzle = new KuzzleSDK.Kuzzle(
    new KuzzleSDK.WebSocket('kuzzle')
  );
  kuzzle.on('networkError', error => {
    console.error('Network Error: ', error);
  });
  kuzzle.on('connected', () => {
    console.log('Successfully connected to Kuzzle');
  });
  kuzzle.connect()
    .then(() => {
      return kuzzle.index.create('nyc-open-data');
    })
    .then(() => {
      return kuzzle.collection.create('nyc-open-data', 'yellow-taxi');
    })
    .then(() => {
      console.log('nyc-open-data/yellow-taxi ready!');
    })
    .catch(error => {
      console.error('Ooops! An error occurred: ', error);
    })
    .then(() => {
      return kuzzle.disconnect();
    });
</script>

Now, let's take a look at what your script is doing:

creates an instance of the SDK,
connects it to Kuzzle running on kuzzle (change the hostname if needed) using WebSocket,
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,
displays an error whenever something goes wrong.

Run this code by opening the index.html file in your favorite browser. The console should output the following message:

Successfully connected to Kuzzle
nyc-open-data/yellow-taxi ready!

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

If you reload the page, you should see an error in the console. This is OK, since Kuzzle is just refusing to create the nyc-open-data index as it already exists.

Create your first "Hello World" document #

Create a create.html file with the same structure as index.html (see above). And, right like before, add some code to the body tag:

<script>
  var kuzzle = new KuzzleSDK.Kuzzle(
    new KuzzleSDK.WebSocket('kuzzle')
  );
  kuzzle.on('networkError', error => {
    console.error('Network Error: ', error);
  });
  kuzzle.on('connected', () => {
    console.log('Successfully connected to Kuzzle');
  });
  kuzzle.connect()
    .then(() => {
      var driver = {
        name: 'Sirkis',
        birthday: '1959-06-22',
        license: 'B'
      };
      return kuzzle.document.create('nyc-open-data', 'yellow-taxi', driver);
    })
    .then(() => {
      console.log('New document successfully created!');
    })
    .catch(error => {
      console.error('Ooops! An error occurred: ', error);
    })
    .then(() => {
      return kuzzle.disconnect();
    });
</script>

This code does the following:

creates an instance of the SDK,
connects it to Kuzzle running on kuzzle (change the hostname if needed) using WebSocket,
creates a new document in the yellow-taxi collection, within the nyc-open-data index
logs a success message to the console if everything went fine
logs an error message if any of the previous actions fails
disconnects from Kuzzle after the document is created or if an error occurs

Run this code by opening the create.html file in your favorite browser. The console should output the following message:

Successfully connected to Kuzzle
New document successfully created!

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

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.html file (same structure as above) with the following code in the body tag:

<script>
  var kuzzle = new KuzzleSDK.Kuzzle(
    new KuzzleSDK.WebSocket('kuzzle')
  );
  var filter = {
    equals: { license: 'B' }
  };
  var callback = (notification) => {
    if (notification.type === 'document' && notification.action === 'create') {
      console.log('New driver ' + notification.result._source.name + ' with id ' + notification.result._id + ' has B license.');
    }
  };
  kuzzle.on('networkError', error => {
    console.error('Network Error: ', error);
  });
  kuzzle.on('connected', () => {
    console.log('Successfully connected to Kuzzle');
  });
  kuzzle.connect()
    .then(() => {
      return kuzzle.realtime.subscribe('nyc-open-data', 'yellow-taxi', filter, callback);
    })
    .then(() => {
      console.log('Successfully subscribed to document notifications!');
    })
    .catch(error => {
      console.error('Ooops! An error occurred: ', error);
      kuzzle.disconnect();
    });
</script>

Run this code by opening the subscribe.html file in a new tab, leaving the previous one (showing create.html) open. The console should output the following message:

Successfully connected to Kuzzle
Successfully subscribed to document notifications!

The code in the subscribe.html page is now running endlessly, waiting for notifications about documents matching its filters, specifically documents that have a license field equal to 'B'.

Now go back to the other tab and reload create.html.

This creates a new document in Kuzzle which, in turn, triggers a document notification sent to the subscribe.html tab. Check the subscribe.html tab: a new message is printed everytime a document is created using the create.html code.

New driver Sirkis with id AWccRe3-DfukVhSzMdUo has B license.

Congratulations! You have just set up your first pub/sub communication!

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:

discover what this SDK has to offer by browsing other sections of this documentation
learn how to use Koncorde to create incredibly fine-grained and blazing-fast subscriptions
learn how to perform a basic authentication
follow our guide to learn how to manage users, and how to set up fine-grained access control

Edit this page on Github

Getting Started with Kuzzle in the browser #

Prepare your environment #

Create your first "Hello World" document #

Subscribe to realtime document notifications (pub/sub) #

Where do we go from here? #