Addon Kit

The ServiceM8 Addon Kit is a command-line tool for building, testing, and deploying ServiceM8 add-ons from your terminal. It provides a modern, repeatable workflow while using the same add-on capabilities, event data, and manifest settings described throughout the Add-on SDK documentation.

Benefits

Addon Kit helps you:

• Scaffold a working TypeScript add-on project.
• Define your add-on in a single addon.jsonc file, with editor autocomplete and validation provided by a JSON schema.
• Bundle TypeScript, multiple source files, and npm dependencies into a deployable serverless function.
• Validate and deploy an add-on from your terminal, or validate it without deploying by using --dry-run.
• Manage add-on secrets without putting secret values in source control. Secrets are supplied to your function as environment variables and can be updated without redeploying.
• Use the same deployment workflow locally and in continuous integration (CI).
• Migrate an existing manifest.json project to the new workflow.

Requirements

Addon Kit requires Node.js 22 or later. Deploying also requires a ServiceM8 account API key with full access. You can create an API key in ServiceM8 under Settings > API Keys. For more information, see Authentication.

Install from npm

Install Addon Kit as a development dependency in your add-on project. A project-local installation keeps the version consistent for everyone working on the add-on and for CI deployments.

npm install --save-dev @servicem8/addon-kit

Run the locally installed CLI with npx:

npx addon-kit --help

Alternatively, install the CLI globally to make the addon-kit command available outside a project:

npm install --global @servicem8/addon-kit
addon-kit --help

Create and deploy an add-on

From the directory where you want to create your add-on, run:

npx @servicem8/addon-kit init my-addon
cd my-addon
npm install --save-dev @servicem8/addon-kit
npx addon-kit login
npx addon-kit deploy

The first command runs the package directly from npm to scaffold the project and create an addon.jsonc configuration file. Installing it as a development dependency then makes npx addon-kit available within the new project. addon-kit login prompts for your ServiceM8 API key, validates it, and stores it outside the project. addon-kit deploy validates the configuration, bundles the function, deploys it, and activates the add-on on the authenticated ServiceM8 account.

To check that an add-on can be bundled and deployed without making any changes to ServiceM8, run:

npx addon-kit deploy --dry-run

The addon.jsonc configuration file

addon.jsonc combines the add-on manifest with Addon Kit settings such as the project slug and function entry point. JSON with Comments (JSONC) lets you document configuration inline, while the included schema provides validation and autocomplete in compatible editors.

{
  "$schema": "./node_modules/@servicem8/addon-kit/addon-schema.json",
  "slug": "job-weather",
  "name": "Job Weather Forecast",
  "version": "1.0",
  "main": "src/index.ts",
  "actions": [
    {
      "name": "Check Weather",
      "type": "online",
      "entity": "job",
      "iconURL": "https://example.com/icon-512.png",
      "event": "check_weather"
    }
  ]
}

The slug uniquely identifies the add-on during deployment. Deploying the same slug updates the existing add-on; changing it creates a new add-on. The remaining manifest fields have the same meaning as those described in the Manifest Reference.

Commands

Run npx addon-kit <command> --help for all options supported by a command.

Use Addon Kit in CI

Set the SM8_API_KEY environment variable in your CI system, then install dependencies and deploy:

- npm ci
- npx addon-kit deploy

Store SM8_API_KEY as a protected or encrypted CI secret. Do not commit an API key to your repository.

Addon Kit deploys serverless add-ons. Your function receives the standard event data, including the short-lived access token used to call the ServiceM8 REST API.