Getting Started with Apps-Engine

Prerequisites

To develop a Rocket.Chat app, you must write TypeScript code. Although the Apps-Engine CLI manages the majority of definitions, you must grasp where the code guides you to comprehend how your application interacts with the Rocket.Chat server and external APIs.

Before beginning, the following must be installed on your machine:

Git
Node.js (version 12 and above)
A code editor. We recommend Visual Studio Code (VSCode).
A Rocket.Chat instance. You can deploy an environment for development and testing purposes. It can be a local instance or available on an HTTPS domain, as per your needs.
Install Rocket.Chat Apps-Engine CLI. The steps are described below.

Install Apps-Engine CLI

The Rocket.Chat Apps-Engine CLI is a command-line interface with which you can develop, deploy, and package Rocket.Chat applications. It provides a set of commands to compile and deploy a basic app structure to your Rocket.Chat server, generate boilerplate code for various functions, display autocomplete installation instructions, submit an app for review in the marketplace, and more.

The CLI is hosted on GitHub and distributed via NPM. It provides an easy interface for developing extensions.

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
```
After installing Node.js, run the following command in your terminal to deploy 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.
After installation, run the following command to verify the installation. Note that the response may differ depending on your system and environment, but it should have a similar appearance. For example, @rocket.chat/apps-cli/1.4.0 darwin-x64 node-v10.15.3
```
rc-apps -v
```
You are now all set to develop your first Rocket.Chat app. To do that, run the command below:
```
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, you can follow the Create an App document to create a basic app and learn about the various Apps-Engine components.

For more information on customization and packaging options, visit the official Rocket.Chat Apps-Engine GitHub repository.

Additional information

The following details help you better understand the Apps-Engine feature.

About Rocket.Chat server

To test your applications, you will need an active server. Ideally, this would be a test environment so as not to impact the production environment. The following components are related to the Rocket.Chat server, and there is no action required from your end:

Server management and package manager: To develop a full-stack JavaScript application, a server-side JavaScript runtime, and a package manager are required. Node.js can be used as the server environment, as it can serve files and connect to the database using JavaScript. For the package manager, we recommend using Yarn due to its faster library installation, better security features, and reliability in managing dependencies.
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 environment extensively used to develop server-side and networking applications. Node.js is designed on top of Chrome's V8 engine, allowing developers to run Javascript programs exceptionally quickly by compiling them directly to machine code.

The virtual machine (VM) module is a fundamental feature of Node.js that allows developers to execute programs in a VM context. The VM module provides access to APIs for compiling and executing code within the context of a V8 VM. The Rocket.Chat Apps-Engine is built on top of the Node.js VM module; therefore, most of the environment configuration will involve launching the VM module within your Rocket.Chat workspace.

About context

With the help of the VM module, a context is an alternative environment that is created. This environment consists solely of key-value pairings, each of which runs directly on top of the V8 engine.

The aim of using the Node.js VM module was to isolate each app on its own scope, preventing them from interacting directly with the host Rocket.Chat server or other apps, so they couldn't inject data and disrupt the system or expose data from other sources. In addition, it is also to avoid the complication of spawning, controlling, and managing the communication of external processes to execute these logics.

Note: The app doesn't have direct access to the VM's APIs. This information is for your understanding.