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
.
- 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
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.7 --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.7"
},
"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 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
AkkaServerless
class, add one or more entities to it, and then invoke
start
, 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~options
.