Developing with JavaScript

The Akka Serverless 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 Akka Serverless 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

Akka Serverless requires at least Node 14. You will find links to download Node here new tab.

Build tool

Akka Serverless 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

Akka Serverless requires Docker new tab 20.10.8 for building your service images. Most popular build tools have plugins that assist in building Docker images.

Since Akka Serverless 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 an Akka Serverless 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 @lightbend/akkaserverless-javascript-sdk package to your service development project, which can be done by running:

npm install @lightbend/akkaserverless-javascript-sdk@0.33.1 --save-exact

To create a basic service, you need to include the akkaserverless 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": {
    "@lightbend/akkaserverless-javascript-sdk": "0.33.1"
  },
  "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.

Precompile the protobuf descriptor set

The gRPC descriptor is serialized to binary using the Protobuf FileDescriptorSet message type. Akka Serverless 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/@lightbend/akkaserverless-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 Akkaserverless class when you got to instantiate it.

Create and start the gRPC server

There are two ways to create and start an Akka Serverless gRPC server. The first is to create an Entitynew tab, and invoke startnew tab 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 AkkaServerlessnew tab class, add one or more entities to it, and then invoke startnew tab, like so:

JavaScript
const AkkaServerless = require("@lightbend/akkaserverless-javascript-sdk").AkkaServerless;

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

server.start();
TypeScript
import { AkkaServerless } from "@lightbend/akkaserverless-javascript-sdk";
import shoppingcartEntity from "./shoppingcart";

new AkkaServerless().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 AkkaServerless({
    descriptorSetPath: "my-descriptor.desc"
});
TypeScript
new AkkaServerless({ descriptorSetPath: "my-descriptor.desc" });

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

What’s next

This section includes information on the following topics: