Creating, Updating & Testing an App

Now, that you've understood the basic concepts of the Apps Engine and installed the CLI, you can create an extremely basic RC App and test it out to understand things initially. To get started, just recall the commands inside the Apps Engine CLI
Creating a new RocketChat App
rc-apps create
The development tools provide a command to quickly scaffold a new Rocket.Chat App, simply run rc-apps create and a new folder will be created inside the current working directory with a basic App which does nothing but will compile and be packaged in the dist folder.
App description
The app description file, named app.json, contains basic information about the app. You can check the app-schema.json file for all the detailed information and fields allowed in the app description file, the basic structure is similar to this:
1
{
2
    "id": "5cb9a329-0613-4d39-b20f-cc2cc9175df5",
3
    "name": "App Name",
4
    "nameSlug": "app-name",
5
    "version": "0.0.1",
6
    "requiredApiVersion": "^1.4.0",
7
    "description": "App which provides something very useful for Rocket.Chat users.",
8
    "author": {
9
        "name": "Author Name <[email protected]>",
10
        "support": "Support Url or Email"
11
    },
12
    "classFile": "main.ts",
13
    "iconFile": "beautiful-app-icon.jpg"
14
}
Copied!
Extending the App class
The basic creation of an App is based on extending the App class from the Rocket.Chat Apps definition library. Your class also has to implement the constructor and optionally the initialize function, for more details on those check the App definition documentation.
Start Developing
In this example, we already have our main file called LiftoffApp.ts that was generated when we first created our project:
1
import {
2
    IAppAccessors,
3
    ILogger,
4
} from '@rocket.chat/apps-engine/definition/accessors';
5
import { App } from '@rocket.chat/apps-engine/definition/App';
6
import { IAppInfo } from '@rocket.chat/apps-engine/definition/metadata';
7
​
8
export class LiftoffApp extends App {
9
    constructor(info: IAppInfo, logger: ILogger, accessors: IAppAccessors) {
10
        super(info, logger, accessors);
11
    }
12
}
Copied!
Now let's add some functionality to it
Adding a Slashcommand
A Slashcommand is a way to call the app installed in Rocket.Chat. Your app can have multiple slashcommands and subcommands. In our example, we will add the liftoff slashcommand and it will be called like this by the user inside the chat room:
1
/liftoff
Copied!
First, we create a new directory called commands in our project's root and create a file called liftoff.ts. You can copy the file's content:
1
import {ISlashCommand, SlashCommandContext} from '@rocket.chat/apps-engine/definition/slashcommands';
2
import {IModify, IRead} from '@rocket.chat/apps-engine/definition/accessors';
3
import {App} from '@rocket.chat/apps-engine/definition/App';
4
​
5
export class LiftoffCommand implements ISlashCommand {
6
    public command = 'liftoff';
7
    public i18nDescription = 'Tells the user if it is time to liftoff';
8
    public i18nParamsExample = '';
9
    public providesPreview = false;
10
​
11
    constructor(private readonly app: App) {}
12
​
13
    public async executor(context: SlashCommandContext, read: IRead, modify: IModify): Promise<void> {
14
        const message = 'Time to lift off!';
15
​
16
        const messageStructure = await modify.getCreator().startMessage();
17
        const sender = context.getSender(); // the user calling the slashcommand
18
        const room = context.getRoom(); // the current room
19
​
20
        messageStructure
21
        .setSender(sender)
22
        .setRoom(room)
23
        .setText(message);
24
​
25
        await modify.getCreator().finish(messageStructure);
26
    }
27
}
Copied!
You can learn more about organizing complex slash commands in our Sub-command pattern recipe
Registering the slashcommand
After adding our slashcomamnd logic, we have to register the slashcommand in our app by extending its configuration:
1
import {
2
    IAppAccessors,
3
    ILogger,
4
    IConfigurationExtend,
5
} from '@rocket.chat/apps-engine/definition/accessors';
6
import { App } from '@rocket.chat/apps-engine/definition/App';
7
import { IAppInfo } from '@rocket.chat/apps-engine/definition/metadata';
8
​
9
import { LiftoffCommand } from './commands/liftoff';
10
​
11
export class LiftoffApp extends App {
12
    constructor(info: IAppInfo, logger: ILogger, accessors: IAppAccessors) {
13
        super(info, logger, accessors);
14
    }
15
​
16
    protected async extendConfiguration(configuration: IConfigurationExtend): Promise<void> {
17
        await configuration.slashCommands.provideSlashCommand(new LiftoffCommand(this));
18
    }
19
}
Copied!
We first had to import the Liftoff class and then register an instance of using the provideSlashCommand function. We pass the app's instance (this) so our slashcommand have access to all the functionalities of the app.
Updating the app
If you want to, for example, change the message sent to the room from Time to lift off! to Lift off now!, you have to simply save the modifications and run:
1
rc-apps deploy --url http://localhost:3000 --username <your_username> --password <your_password> --update
Copied!
The app will be updated and by sending /liftoff, the message will reflect the change you have made in the app.
Testing the App
Now that you have your App ready, you can test it before submitting it.
To test your app, you need a Rocket.Chat server running locally on your machine and an admin user in it.
See Installing Rocket.Chat for Developing to run Rocket.Chat in develop mode. Enable Apps development mode by navigating to Administration > General then scroll down to Apps and click on the True radio button over the Enable development mode.
or run it in preview mode with docker using the command:
1
docker run -it --rm -p 3000:3000 -v `pwd`/rocketdb:/var/lib/mongodb rocketchat/rocket.chat.preview
Copied!
Having the server running, simply run inside the app project's directory:
1
rc-apps deploy --url http://localhost:3000 --username user_username --password user_password
Copied!
Where:
http://localhost:3000 is your local server URL (if you are running in another port, change the 3000 to the appropriate port)
user_username is the username of your admin user.
user_password is the password of your admin user.
If you want to update the app deployed in your Rocket.Chat instance after making changes to it, you can run:
1
rc-apps deploy --url http://localhost:3000 --username user_username --password user_password --update
Copied!
After version 1.9 of the App Engine CLI, the --update flag isn't strictly necessary for updating an existing App, you can just run the deploy command without it.

Understanding the RC Apps Lifecycle

Event Interfaces

Last modified 10h ago

Export as PDF

Copy link

Edit on GitHub

Contents

Creating a new RocketChat App

rc-apps create

App description

Extending the App class

Start Developing

Adding a Slashcommand

Registering the slashcommand

Updating the app

Testing the App