Getting Started with Apps-Engine

Prerequisites

Before you begin developing a Rocket.Chat app, ensure your environment meets the following requirements:

Git
Node.js: Version 12 or higher is required. You can check your version by running node -v in your terminal.
A code editor: We recommend using Visual Studio Code (VSCode) for its robust TypeScript support.
A Rocket.Chat instance: You'll need a server for testing your app. You can deploy a development environment locally or on an HTTPS domain.
Rocket.Chat Apps-Engine CLI: This is the command-line tool used to generate, build, and deploy apps. Installation instructions are below.

You must be comfortable working with TypeScript, as Rocket.Chat apps are written in it. The CLI automates much of the setup, but understanding the structure and API interactions is essential for development.

Installing Apps-Engine CLI

The Rocket.Chat Apps-Engine CLI is a command-line tool used to develop, deploy, and package Rocket.Chat applications. It enables you to:

Create boilerplate app structures
Compile and deploy apps to a Rocket.Chat server
Display autocomplete instructions
Submit apps to the Rocket.Chat Marketplace and more

The CLI is open-source, hosted on GitHub, and distributed via NPM.

Follow these installation steps:

Before installing the CLI, you must ensure that Node.js is installed on your system. Use the following command in your terminal to verify the installation of Node.js. This returns a valid version of Node.js, for example, v10.15.3:
```
node -v
```
Once Node.js is installed, run the following command to install the Rocket.Chat Apps-Engine 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.
After installing the CLI, run the following command to verify that it's installed correctly:
```
rc-apps -v
```
You should see output similar to:
```
@rocket.chat/apps-cli/1.4.0 darwin-arm64 node-v16.15.3
```
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
```
With the CLI installed, you’re ready to develop your first Rocket.Chat app. Run:
```
rc-apps create
```
This command will guide you through a brief setup process by asking for details about your app. On providing this information, a basic Rocket.Chat app structure will be created in the current working directory.

Next steps

Follow the Create an App guide to learn about the file structure, API usage, and extending functionality.
For customization, advanced packaging, and deployment options, explore the Rocket.Chat Apps-Engine GitHub repository.

Additional information

The following details provide context about how the Apps-Engine interacts with the Rocket.Chat server.

About Rocket.Chat server

To test your applications, you’ll need access to an active Rocket.Chat server. Ideally, this should be a dedicated test environment to avoid affecting your production setup.

The following components relate to the Rocket.Chat server and typically require no action from your side:

Server management and package manager:
- To develop full-stack JavaScript applications, a server-side runtime and a package manager are essential.
- Rocket.Chat uses Node.js as its server environment, which handles file serving, backend logic, and database connectivity via JavaScript.
- For managing dependencies, Yarn is recommended due to its speed, improved security features, and more reliable dependency handling compared to npm.
Database: You need a database to store your application data. The Rocket.Chat server uses MongoDB as a database to store all chat messages, user information, and other system configurations and related data.

About Node.js VM module

Node.js is a cross-platform, open-source JavaScript runtime commonly used for building server-side and networking applications. It runs on Chrome’s V8 engine, which compiles JavaScript directly into machine code for high performance.

Rocket.Chat's Apps-Engine is built on top of the Node.js VM module, a core feature that allows code to be executed in a sandboxed virtual machine (VM) context. This means that when you run a Rocket.Chat app, the engine uses the VM module to safely execute your code in isolation from the rest of the system.

About VM context

A VM context is a controlled execution environment created using the VM module. It functions as a key-value sandbox, where each app runs in its own space directly on the V8 engine.

The goal of using the VM module is to:

Isolate each app so it cannot access or interfere with Rocket.Chat’s core system or other apps.
Prevent data injection or leakage between apps.
Avoid complexity related to managing separate external processes for app execution.

This ensures that Rocket.Chat apps remain safe, secure, and self-contained.

Apps do not have direct access to the VM module’s APIs. This explanation is provided only to help you understand how app isolation works behind the scenes.