Implementation basics

To create a basic Cloudstate service you need to include the cloudstate package, define a gRPC descriptor in a .proto file and add logic to start the gRPC server. The sections on this page describe how to accomplish these tasks in Javascript.

Include the cloudstate package

A minimal package.json for a shopping cart example is shown below:

  "name": "shopping-cart",
  "version": "0.1.0",
  "dependencies": {
    "cloudstate": "^0.0.3"
  "scripts": {
    "prestart": "compile-descriptor shoppingcart.proto",
    "start": "node index.js"

Define gRPC descriptor

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 gRPC descriptors in a file in the root folder called shoppingcart.proto.

Precompile the protobuf descriptor set

The gRPC descriptor is serialized to binary using the Protobuf FileDescriptorSet message type. Cloudstate requires that you precompile 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/cloudstate/bin/compile-descriptor.js.

Or, add a prestart script to your npm build:

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

compile-descriptor utility options

Multiple protobuf files can be passed to the compile-descriptor utility. You can also pass any arguments accepted by protoc. Ror 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 CloudState class when you got to instantiate it.

Create and start the gRPC server

There are two ways to create and start a Cloudstate gRPC server. The first is to create an Entity, and invoke start on it. This allows creating a server that serves a single entity, with the default options. We’ll look at this more in the subsequent pages. Alternatively, you can use the CloudState class, add one or more entities to it, and then invoke start, like so:

const cloudstate = require("cloudstate");
const shoppingcart = require("./shoppingcart");

const server = new cloudstate.CloudState();

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

const server = new cloudstate.CloudState({
    descriptorSetPath: "my-descriptor.desc"

For the full range of options available on the CloudState class, see CloudStateoptions.