Services

Roli hosts serverless cloud backends called Services that your applications can access at runtime using automatically generated client code.

Service Code

Services are comprised of functions and POJOs (Plain Old JavaScript Objects) written in TypeScript.

Service Creation

To create a service, create a new folder and initialize it. Initializing creates a service.json file inside the folder that contains the service’s name and other service metadata.

To initialize a service you use the init-service command, passing the directory and the service’s name

$ mkdir my-service
$ cd my-service
$ roli init-service my-service-name

You can only initialize a service once.

Caution

You should store the service.json file as well as the roli-runtime directory in source control.

Service Deployment

Once the service code is written, or you’ve made code changes, you must deploy it to Roli before it can be used.

To deploy your service code changes use the deploy-service command in the service directory:

$ cd my-service
$ roli deploy-service

Or you can specify the -d option to specify the service directory to deploy:

$ roli deploy-service -d my-service

The deploy-service command deploys the service if it finds there are changes to deploy. This makes it safe to use this command in CI scripts.

However, if there’s a need to override the change detection, use the —force option:

$ roli deploy-service --force

Service Version

Each time you deploy your service it increments the service version number. Doing so ensures clients can’t use out of date service code, preventing certain types of data corruption.

Listing Deployed Services

You can show the list of services, along with their versions, that have been deployed using the list-services command.

roli list-services

Renaming Services

You can change the name of your service using this process:

1. Change the name of the service in the service.json file in the service code directory.
2. Deploy the service to complete the renaming.

Caution

If you’ve used the roli generate-client command to create a client module for the old service name, you’ll need to manually delete the old client module from your client projects.

1. Delete the .roli/bindings/<old-service-name> folder.
2. Delete the dependency from the package.json

"dependencies": {
    ...
    "<old-service-name>-service": "file:./.roli/bindings/<old-service-name>"
  },

3. Run pnpm i (or npm install etc) to clean up your node_modules directory.
4. Use the roli generate-client command to generate a new client module for the new service name.
5. Update client code imports to reference the new service name:

// Client code

import {MyApi} from "<old-service-name>-service"
// to
import {MyApi} from "<new-service-name>-service"