Develop your Desktop App

To improve long-term maintainability, the Rocket.Chat desktop application has been fully rewritten in TypeScript 5. This aligns the desktop client with ongoing changes across the Rocket.Chat ecosystem and provides stronger guarantees around type safety and refactoring.

Understand the build pipeline

The foundation of the build process relies on the rollup bundler, which is responsible for compiling and integrating all components. The codebase has three primary entry files:

• src/main.ts: Runs during the main electron process, orchestrating the whole application.

• src/rootWindow.ts: Handles the rendering and logic for the primary UI window.

• src/preload.ts: Executes in a privileged preload context, acting as a secure bridge between the Electron environment and the embedded Rocket.Chat web client.

Understanding these boundaries is essential when modifying startup behavior, UI initialization, or IPC communication.

Manage dependencies

When extending the application with additional Node.js modules, dependency classification in the package.json file matters.

• Modules listed under dependencies are bundled into the final distributable application.

• Modules listed under devDependencies are used only during development and build time.

Only dependencies declared under dependencies will be shipped with the packaged desktop app.

Misclassifying a runtime dependency as a dev dependency will result in missing modules in production builds.

Configure default servers

Default servers allow you to predefine one or more Rocket.Chat workspaces for the desktop app to connect automatically, without requiring manual input from the user on first launch. It automatically populates the sidebar for new users, removing the need for them to enter a URL manually.

To configure default servers, you can either bundle it with the installation package or configure it after installation.

How it works

When the Rocket.Chat desktop app starts, it determines whether it should prompt the user to connect to a server or automatically use a predefined configuration, following this order:

1. If the user has already added one or more servers, the default server mechanism is skipped entirely.

2. If no servers exist, the app looks for a servers.json configuration file to load the default server configuration.

3. When servers.json is found, the app skips the "Connect to Server" screen and loads the first server in the list immediately. It also uses the contents of servers.json to populate the server sidebar automatically.

This ensures that default servers are applied only for first-time or reset states, and never overwrite user-defined configuration.

Bundle the default servers with the app

If you are building a custom version of the app, continue with these steps to bundle default servers with the installation package:

1. Create a servers.json file at the project root on the same level as package.json.

2. Add the servers following this syntax mapping the Server Name to the Workspace URL. For example:

   {
     "Demo Rocket Chat": "https://demo.rocket.chat",
     "Open Rocket Chat": "https://openrocket.chat",
     "Awesome Rocket Chat": "https://awesome.rocket.chat"
   }

3. Run this command:

   yarn start

The servers listed in the JSON file are now loaded in the desktop app sidebar, prompting you to log in to the first server.

Note that the servers.json file will only be checked if no other servers have been added previously. Even if you uninstall the app without removing previous preferences, this check will not be triggered again.

Override default servers during installation

If you can’t bundle default servers with the installation package, you can create a servers.json in your user preferences folder after installing the desktop app to overwrite the packaged one.

1. Locate your user preference directory for Rocket.Chat similar to any of these below, depending on your operating system:

2. Create a servers.json file following this syntax mapping the Server Name to the Workspace URL. For example:

{
  "Demo Rocket Chat": "https://demo.rocket.chat",
  "Open Rocket Chat": "https://openrocket.chat",
  "Awesome Rocket Chat": "https://awesome.rocket.chat"
}

3. Launch the installed desktop application and it’ll populate the default servers defined in the servers.json file.

Unit tests

Unit testing is implemented using Jest with the Jest electron runner. The test runner searches for all files in the src/ directory that matches the following pattern and performs tests on them:

*.(spec|test).{js,ts,tsx}

Run this command to execute tests on your changes:

yarn test

Build a release installer

To package the Rocket.Chat desktop application into a distributable installer,

1. Compile your app changes to make it production ready:

   yarn build

2. Run this command:

   yarn release

   This process compiles the code and bundles it into platform-specific formats (e.g., .dmg for macOS, .exe for Windows). The command above initiates the packaging procedure for the specific operating system you're currently using.

3. Once completed, the resulting output file is prepared for distribution and can be located in the dist/ directory. You can proceed to distrubute the installer for users to have your customized Rocket.Chat desktop app.

It's important to note that electron-builder manages all packaging operations, and it offers many customization possibilities.

Building for MacOS locally

If you are building on macOS without an Apple Developer Certificate, you must bypass code signing and specify a non-App Store target to avoid build failures with this command:

CSC_IDENTITY_AUTO_DISCOVERY=false yarn release --mac dmg

• CSC_IDENTITY_AUTO_DISCOVERY=false: Prevents the builder from searching for system certificates.

• --mac dmg: Forces the output to a disk image, bypassing the strict signing requirements of the Mac App Store (mas) target.

The succesful build is stored in dist/rocketchat-[version]-mac.dmg.

If you encounter an error or unexpected behavior, you can follow the debugging options we have documented.