Developer Tools

The JavaScript tooling is published to the npm registry under the @kalix-io organisation.

Kickstart

Entity initialization is provided via the create-kalix-entity command line tool. This tool requires only a name for the new entity, and creates a new npm project directory with the Kalix SDK and associated development support tooling set up.

An initial codebase for a new entity can be created using either npm or Yarn:

npm
npx @kalix-io/create-kalix-entity@latest my-entity
cd my-entity
npm install
npm run build
Yarn
yarn create @kalix-io/kalix-entity@latest my-entity
cd my-entity
yarn
yarn build

Ongoing development support

The development support tooling is provided via a single npm package; kalix-scripts. This package is intended to be invoked from your npm scripts configuration and provides a single script designed to be invoked from the command line.

Commands

The kalix-scripts script is expected to be invoked with a single argument, specifying one of the following commands:

  • build; generates implementation stubs for your entity/service and corresponding tests, as well as a refined Typescript interface for your implementation to implement. This interface is referenced in the generated implementation using JsDoc, such that any Typescript-aware editor (such as VS Code) can leverage it. If you make further updates to your Protobuf specification after the initial generation, existing implementation is left unchanged but the interface is updated to align. This allows you to leverage native developer tooling to guide the desired changes.

  • package; invokes the Docker CLI to build a deployable image, based on a Dockerfile expected to exist in the root directory of your project. The Kickstart tool generates a suitable Dockerfile, however you can modify or replace this to suit your needs.

  • deploy; invokes the kalix command line tool to deploy the service to Kalix. This relies on an existing installation of the CLI and uses configuration and credentials from that installation.

The deploy command requires the Kalix CLI to be installed on your system.

Installation

The package can be added to your project via npm:

npm install --save-dev @kalix-io/kalix-scripts

Configuration

Configuration is pulled from the config section of your project’s package.json, and the command will fail if any required configuration is not present. For example:

  "config": {
    "dockerImage": "my-docker-repo/my-image",
    "sourceDir": "./src",
    "testSourceDir": "./test",
    "protoSourceDir": "./proto",
    "generatedSourceDir": "./lib/generated"
  },