Quickstart: Customer Registry in TypeScript

From the command line, create a directory with the basic structure for your project using a template:

npx @kalix-io/create-kalix-entity@latest customer-registry --typescript --template basic

Change into the project directory:

cd customer-registry

Download and install project dependencies:

npm install

Create a proto directory.

mkdir proto

Create a customer_api.proto file and save it in the proto directory.

Add declarations for:

syntax = "proto3";

package customer.api;

import "google/protobuf/empty.proto";
import "kalix/annotations.proto";

Add the service endpoint. The service endpoint is annotated with kalix.codegen indicating we want to generate a Value Entity for this service.

service CustomerService {
  option (kalix.codegen) = {
    value_entity: {
      name: "customer.domain.Customer"
      entity_type: "customers"
      state: "customer.domain.CustomerState"
    }
  };

  rpc Create(Customer) returns (google.protobuf.Empty) {}
  rpc GetCustomer(GetCustomerRequest) returns (Customer) {}
}

Add messages to define the fields that comprise a Customer object (and its compound Address):

message Customer {
  string customer_id = 1 [(kalix.field).entity_key = true];
  string email = 2;
  string name = 3;
  Address address = 4;
}

message Address {
  string street = 1;
  string city = 2;
}

Add the message that will identify which customer to retrieve for the GetCustomer message:

message GetCustomerRequest {
  string customer_id = 1 [(kalix.field).entity_key = true];
}

Create a customer_domain.proto file and save it in the proto directory.

Add declarations for the proto syntax and domain package.

syntax = "proto3";

package customer.domain;

Add the CustomerState message with fields for the customer data, and the Address message:

message CustomerState {
  string customer_id = 1;
  string email = 2;
  string name = 3;
  Address address = 4;
}

message Address {
  string street = 1;
  string city = 2;
}

Run the build script from the project root directory to generate source classes, based on the protobuf definitions, in which you can add the business logic:

npm run build

If it’s not open already, open the generated src/customer.ts file for editing.

Modify the Create handler by adding the logic to handle the command. The complete function should include the following:

Create(customer, _customerState, ctx) {
  // API and domain messages have the same fields so conversion is easy
  const customerState = CustomerState.create(customer);
  ctx.updateState(customerState);
  return Reply.message({});
},

Modify the GetCustomer handler as follows to handle the GetCustomerRequest command:

GetCustomer(getCustomerRequest, customerState) {
  if (!customerState.customerId) {
    const id = getCustomerRequest.customerId;
    return Reply.failure(`Customer ${id} has not been created.`);
  } else {
    // API and domain messages have the same fields so conversion is easy
    return Reply.message(customerState);
  }
},

If you haven’t done so yet, sign in to your Kalix account. If this is your first time using Kalix, this will let you register an account, create your first project, and set this project as the default.

kalix auth login

Update the config.dockerImage setting in the package.json file with your container registry.

Use the deploy script to build the container image, publish it to the container registry as configured in the package.json file, and then automatically deploy the service to Kalix using kalix:

npm run deploy

You can verify the status of the deployed service using:

kalix service list