Getting Started with Rocket Chat Apps-Engine

Learn how to set up your environment and create your first Rocket.Chat app with the Apps-Engine CLI.

Prerequisites

Before you begin, make sure you have:

Node.js (current LTS) and npm: Required to install and run the Apps-Engine CLI.
A code editor: Visual Studio Code (VS Code) is recommended for TypeScript support.
A Rocket.Chat workspace: A running Rocket.Chat server with admin access, used to deploy and test your app. It isn't required to create the project. You can deploy one locally for development. Avoid using a production workspace.
Rocket.Chat Apps-Engine CLI: Creates, packages, and deploys apps. Installation steps are below.
Git (optional): Recommended for version control of your app project.

Rocket.Chat apps are written in TypeScript. The CLI scaffolds much of the project for you, but you should be comfortable reading and editing TypeScript.

Install the Apps-Engine CLI

The Apps-Engine CLI (@rocket.chat/apps-cli) helps you:

Create a boilerplate app
Compile and package apps
Deploy apps to a Rocket.Chat server
Submit apps to the Rocket.Chat Marketplace
Configure shell autocomplete

The CLI is open source and available on GitHub.

Verify that Node.js and npm are installed:
```
    node -v
    npm -v
```

Both commands return a version number, for example v22.17.0 and 10.9.2. If not, install the current LTS release of Node.js, which includes npm.

Install the CLI globally:
```
    npm install -g @rocket.chat/apps-cli
```
Troubleshooting tip
Error: While attempting to execute the preceding command, if your operating system rejects the operation, it is likely that you do not have permission to access the file as the current user. If you suspect a permissions issue, please double-check your NPM installation, or rerun the command as root/administrator.

Resolution: Prefix the command with sudo and execute as follows:
```
sudo npm install -g @rocket.chat/apps-cli
```
After executing this command, enter the system user's password. This will grant the application all necessary permissions, as this command must be executed as an administrator.
Verify the CLI installation:
```
    rc-apps -v
```
You should see output similar to:
```
    @rocket.chat/apps-cli/1.14.0 darwin-arm64 node-v22.17.0
```
This confirms that the CLI is correctly installed and ready to use.
If you receive an error like command not found, ensure your global npm binaries are in your system’s PATH. You can check this by running:
```
npm bin -g
```

Next steps

Your environment is ready. Continue to Create an App to create your first app with rc-apps create, explore the project structure, and deploy it to your workspace.

To see all available CLI commands, run rc-apps help.

Additional information

Rocket.Chat workspace for testing

To install and test apps end-to-end, use a dedicated Rocket.Chat workspace (local or remote). Avoid deploying experimental apps to production. See Deploy Rocket.Chat if you need a workspace for testing.

Apps runtime on the server

Apps run inside a runtime managed by the Rocket.Chat server, so you don't need to host them separately. Starting with Rocket.Chat 8.8.0, apps use the Node.js runtime backend by default. This doesn't change how you install, configure, or manage apps in Administration.

The Deno runtime was removed in Rocket.Chat 8.9.0. Workspaces on Rocket.Chat 8.8.x can still use the Deno runtime by setting the APPS_ENGINE_RUNTIME_BACKEND environment variable. See Deployment environment variables for details.