Create an App

This document will guide you through using the Apps-Engine CLI to create a basic Rocket.Chat app.

Before continuing, make sure you’ve completed the CLI installation and environment setup. You can follow the full instructions here: Getting Started with Apps-Engine

Once your setup is ready and the CLI is installed, you’ll build a simple Hello World app to get familiar with the basic structure and workflow of a Rocket.Chat app.

Step 1: Run the create command

To begin creating your app, open your terminal and run the following command:

rc-apps create

This command will prompt you to enter some basic information about your app. You can use the following example values:

• App Name: Hello World

• App Description: A basic app that prints Hello World!

• Author’s Name: John

• Author’s Home Page: rocketchat.com

• Author’s Support Page: support.rocketchat.com

Once completed, the CLI will generate a new folder named after your app (e.g., hello-world). This folder contains all the files for your Rocket.Chat app, including boilerplate code and configuration. A dist/ folder will also be created when the app is packaged or compiled.

Troubleshooting tip

If you encounter the following error after running rc-apps create:

'TypeError: Cannot read properties of undefined [reading 'message']'.

This is a known issue and does not affect app creation. You can ignore the error and verify that your app folder was successfully created by running:

cd <folder-name>  

Step 2: Open the app folder in Visual Studio

1. Launch Visual Studio Code.

2. From the left sidebar, click File > Open Folder (or use the welcome screen shortcut).

3. Navigate to and select the app folder you just created (e.g., hello-world).

4. Once opened, you’ll see the folder structure in the Explorer sidebar.

Step 3: Understand the app structure

• The app.json file (also called the app manifest) contains metadata and configuration details for your app:

{
    "id": "28d63257-94c3-40e8-83eb-9581244598b6",
    "version": "0.0.1",
    "requiredApiVersion": "^1.4.0",
    "iconFile": "icon.png",
    "author": {
        "name": "John",
        "homepage": "rocketchat.com",
        "support": "support.rocketchat.com"
    },
    "name": "Hello World",
    "nameSlug": "hello-world",
    "classFile": "HelloWorldApp.ts",
    "description": "A basic app that prints Hello World!"
}

• A Rocket.Chat app is a TypeScript project that includes a main file with a class extending the core App class provided by the Apps-Engine.

• The entry point for this file is defined in the classFile property of app.json. In this example, it points to HelloWorldApp.ts. Open the HelloWorldApp.ts file to explore the app's primary logic.

• The following code snippet shows the contents of the HelloWorldApp.ts file:

import {
    IAppAccessors,
    ILogger,
} from '@rocket.chat/apps-engine/definition/accessors';
import { App } from '@rocket.chat/apps-engine/definition/App';
import { IAppInfo } from '@rocket.chat/apps-engine/definition/metadata';

export class HelloWorldApp extends App {
    constructor(info: IAppInfo, logger: ILogger, accessors: IAppAccessors) {
        super(info, logger, accessors);
    }
}

• The class name and the filename (HelloWorldApp.ts) are intentionally the same. This is required for the app to compile successfully, unless you export the class as default, as shown below:

export default class HelloWorldApp extends App {
    // ...
}

• To create a functional Rocket.Chat app, your main class must include a constructor. This constructor gives you access to several key parent-level properties required to build app functionality.

  The constructor accepts three arguments:

  • IAppInfo: Contains basic metadata about the app, such as name, version, and description.

  • ILogger : Provides an interface for logging. You can access it from your class using the this.getLogger() method.

  • IAppAccessors : Includes all accessor interfaces available to the app. Use this.getAccessors() to retrieve this object from within the child class.

For in-depth information about the available modules, interfaces, and types, refer to the Rocket.Chat Apps Typescript definition.

Step 4: Implement the app functionality

In this example, the app logs "Hello, World!" to the Rocket.Chat administration interface.

To log data, you’ll use an object of type ILogger. The parent App class logs to the admin interface using this object. However, since logger is private to the App class, it can’t be accessed directly via this.

Instead, use the getLogger() method, which returns an ILogger instance. Store it in a class-level variable for reuse throughout your app.

Update the class in HelloWorldApp.ts as follows:

export class HelloWorldApp extends App {
    private readonly appLogger: ILogger
    
    constructor(info: IAppInfo, logger: ILogger, accessors: IAppAccessors) {
        super(info, logger, accessors)
        this.appLogger = this.getLogger()
    }
}

Now that appLogger is available, you can log messages like this:

this.appLogger.debug('Hello, World!')

Step 5: Deploy the app to the server

In your terminal, navigate to the hello-world app folder created in Step 1.

To deploy the app, run:

rc-apps deploy --url <server_url> -u <user> -p <pwd>

• Replace <server_url> with the URL of your Rocket.Chat workspace.

• Replace <user> and <pwd> with your Rocket.Chat username and password.

After running the command, your app will be deployed to the server.

To see more authentication options (such as 2FA tokens or personal access tokens), run:

rc-apps deploy --help

Packaging your app

Alternatively, you can run rc-apps package to generate a .zip file of your app. This file can be uploaded manually to your Rocket.Chat server as a private app.

Step 6: Test the app

To test your app, you need a Rocket.Chat server running locally on your machine and the credentials of an administrator user.

In older versions of Rocket.Chat, you might need to enable apps development mode for manual installations to be allowed.

To enable apps development mode:

• Go to Administration > General > Apps.

• Click True next to Enable development mode.

To run Rocket.Chat in develop mode, see the development environment setup guide.

In this example, the function of the application is to log Hello, World! to the console. To test the app's functionality, we must examine the app logs.

Follow these steps to examine the logs:

1. Login to your Rocket.Chat workspace as an admin.

2. Navigate to the Administration Panel.

3. Under Apps, select Marketplace.

4. Select Private Apps from the left-hand menu. You should see the Hello World app.

5. Click on the three dots icon on the right-hand side of the app. From the menu, click on View Logs.

6. The App Info page opens on the Logs tab. Use the filters or scroll through the list to find the constructor log entry, then expand it to see the "Hello, World!" message.

Congratulations, you just created your first app, a simple Hello World app!

To learn how to add more functionalities to your app, proceed to the next topic.

Apps-Engine CLI commands

The rc-apps CLI is a command-line tool that helps you quickly scaffold, develop, and manage Rocket.Chat applications.

To get started, run the following command in your terminal to see available options:

rc-apps

Here are the core commands supported by the Apps-Engine CLI:

Troubleshooting