Core
Guides v2.x
2

Write an Application #

Kuzzle is fully extensible like any framework. This extensibility is available through the development of an application.

Several classes and methods are available to developers so that they can develop their new business functionalities.

The Backend class #

The Backend class is the entrypoint of any Kuzzle application.

First we need to instantiate it with an application name:

Copied to clipboard!
import { Backend } from 'kuzzle'

const app = new Backend('playground')

An application has two phases: setup and runtime. The classes and methods that can be used depend on the phase the application is in.

Calling the Backend.start method will start your application and change it's phase to runtime.

Register new features #

When the application is in the setup phase, it exposes methods allowing to register new features to Kuzzle, such as:

  • controllers: extend the API
  • pipes: modify the API behavior
  • hooks: execute asynchronous processing
  • plugins: add whole set of features

Example: Registering a new Controller with the Backend.controller.register method

Copied to clipboard!
// Before application startup
app.controller.register('greeting', {
  actions: {
    sayHello: {
      handler: async request => {
        return `Hello, ${request.input.args.name}`
      }
    }
  }
})

Once the features have been registered, it is possible to start our Kuzzle application with the Backend.start method.

Once the application has been started with the Backend.start method, it is no longer possible to register new features.

We will see in detail how to add controllers and pipes in the next chapters of this guide.

Interact with the application #

Once the application has started, methods to interact with it become available.

In particular, those methods make it possible to:

  • Use the Embedded SDK to execute API actions
  • Trigger Events
  • Log Messages
  • And much more!

Example: Use the Embedded SDK to create an index after startup with the index.create method

Copied to clipboard!
app.start()
  .then(async () => {
    // Interact with Kuzzle API to create a new index if it does not already exist
    if (! await app.sdk.index.exists('nyc-open-data')) {
      await app.sdk.index.create('nyc-open-data')
    }
  })
  .catch(console.error)

Some methods interact directly with the Kuzzle API and with internal modules. Therefore they aren't available until the application has been started with the Backend.start method.

Embedded SDK #

In order to use the API actions, Kuzzle exposes an EmbeddedSDK instance through the Backend class.

You can access it through the Backend.sdk property.

The Embedded SDK is a modified version of the Javascript SDK which is directly connected to the API and does not send requests through the network.

Example: Create a new document by using the document.create method

Copied to clipboard!
// After application startup

// [...]

// Creates a document
await app.sdk.document.create('nyc-open-data', 'yellow-taxi', {
  name: 'Aschen',
  age: 27
})

The low level query method can also be used to send custom requests to the Kuzzle API.

Example: Execute a custom controller action with the query method

Copied to clipboard!
// After application startup

// [...]

// Execute a custom controller action
await app.sdk.query({
  controller: 'greeting',
  action: 'sayHello',
  name: 'Aschen'
})

Complete example #

Copied to clipboard!
import { Backend } from 'kuzzle'

// Instantiate an application
const app = new Backend('playground')

// Now we can register features

// Register a new controller
app.controller.register('greeting', {
  actions: {
    sayHello: {
      handler: async request => {
        return `Hello, ${request.input.args.name}`
      }
    }
  }
})

// Start the application
app.start()
  .then(async () => {
    // Now we can interact with Kuzzle API

    // Interact with Kuzzle API to creates a new index if it does not exists
    if (! await app.sdk.index.exists('nyc-open-data')) {
      await app.sdk.index.create('nyc-open-data')
    }
  })
  .catch(console.error)