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
Having trouble? Get in touch with us on Discord!
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
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:
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 SDKfrom its NPM package - creates an instance of the SDK and connects it to Kuzzle running on
localhost(and selects theplaygroundas default index), - creates the
playgroundindex, - creates the
mycollectioncollection (within theplaygroundindex), - 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
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:
// 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
mycollectionwithin theplaygroundindex, - 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 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:
// 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!
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)