JavaScript/TypeScript Protobuf SDK

The Kalix JavaScript SDK offers an idiomatic JavaScript language SDK for writing components. This page describes prerequisites for JavaScript development and basic requirements for a development project.

Lightbend provides Tier 1 support for the JavaScript SDK. See an explanation of support tiers for more information.

Your development project needs to include the Kalix JavaScript SDK and logic to start the gRPC server. You define your components in gRPC descriptors and use protoc to compile them. Finally, you implement business logic for service components.

To save the work of starting from scratch, the JavaScript code generation tool creates a project, complete with descriptors and implementations. Or, you can start from one of our Quickstarts.

Prerequisites

The following are required to develop services in JavaScript:

Node

Kalix requires at least Node 18. You will find links to download Node here new tab.

Build tool

Kalix does not require any particular build tool, you can select your own but out-of-the-box experience is provided in conjunction with npm and Yarn.

Docker

Kalix requires Docker new tab 20.10.14 for building your service images. Most popular build tools have plugins that assist in building Docker images.

Since Kalix is based on gRPC, you need a protoc compiler to compile gRPC protobuf descriptors. The SDK provides helper scripts to automatically download the protoc compiler for your platform and compile your project.

Development project requirements

The following examples show how to install the SDK to build your services with npm or Yarn. The code generation tools include a Kalix code generation tools that generates the recommended project structure, including a package.json file with the necessary references.

The code generation tools do more than just provide a starter project, after you modify a .proto file, they will generate code stubs for the elements you changed or added.

If you are starting from scratch, you will need to add configuration and code to:

Add SDK libraries

Once you have the prerequisites, you need to add the @kalix-io/kalix-javascript-sdk package to your service development project, which can be done by running:

npm install @kalix-io/kalix-javascript-sdk@1.1.0 --save-exact

To create a basic service, you need to include the kalix package dependencies in your project, define gRPC descriptors in .proto files and reference them in your project, compile the .proto files, and have logic to start the gRPC server in your source code.

The following shows a minimal package.json configuration for a shopping cart service project:

{
  "name": "shopping-cart",
  "version": "0.1.0",
  "dependencies": {
    "@kalix-io/kalix-javascript-sdk": "1.1.0"
  },
  "scripts": {
    "prestart": "compile-descriptor shoppingcart.proto",
    "start": "node index.js"
  }
}

Define gRPC descriptors and compile

Descriptors for gRPC are defined in protobuf files. You can place protobuf files in your project wherever you like, for example, in the root directory, or in a directory named protos. In the package.json example, above we’ve placed the service descriptor in a file in the root folder called shoppingcart.proto. See Writing gRPC descriptors for more details.

Pre-compile the protobuf descriptor set

The gRPC descriptor is serialized to binary using the Protobuf FileDescriptorSet message type. Kalix requires that you pre-compile this descriptor using protoc. We provide a utility that does this for you. It downloads the protoc binary for your platform, and runs it with the necessary arguments and include paths. You can run the utility manually, or we recommend adding it as a script to the build.

To run the utility manually, invoke node_modules/@kalix-io/kalix-javascript-sdk/bin/compile-descriptor.js.

Or, add a prestart script to your npm build:

{
  "scripts": {
    "prestart": "compile-descriptor my-descriptor.proto"
  }
}

The compile-descriptor utility

Multiple protobuf files can be passed to the compile-descriptor utility. You can also pass any arguments accepted by protoc. For example, if you are importing files from other directories, you can add those directories as an include path by adding -Ipath/to/protobuf/dir.

By default, the descriptor is written to user-function.desc, if you wish to change this, you can set --descriptor_set_out=my-descriptor.desc. Note that if you output the descriptor to a different path, you will also need to pass that custom path to the constructor of the kalix class when you got to instantiate it.

Create and start the gRPC server

Use the Kalixnew tab class, add one or more Componentsnew tab to it, and then invoke startnew tab, like so:

JavaScript
const Kalix = require("@lightbend/kalix-javascript-sdk").Kalix;

const server = new Kalix();
server.addComponent(require("./shoppingcart"));

server.start();
TypeScript
import { Kalix } from "@kalix-io/kalix-javascript-sdk";
import shoppingcartEntity from "./shoppingcart";

new Kalix().addComponent(shoppingcartEntity).start();

If you created your protobuf file descriptor set at a different location to the default of user-function.desc, you can configure that here:

JavaScript
const server = new Kalix({
    descriptorSetPath: "my-descriptor.desc"
});
TypeScript
new Kalix({ descriptorSetPath: "my-descriptor.desc" });

For all options available on the Kalix class, see Kalix~optionsnew tab.