Mac OS Rocket.Chat Development Environment Setup

This guide walks you through setting up a local Rocket.Chat development environment on macOS systems running on Apple silicon or Intel processors.

Prerequisites

Install the following dependencies before you begin:

Homebrew: Package manager for macOS used to install required system dependencies.
Yarn: Package manager used to install project dependencies.

Verify that each dependency is installed:

brew --version
yarn --version

Step 1: Clone the Rocket.Chat repository

Clone the official Rocket.Chat repository to your local machine:
```
git clone https://github.com/<your-username>/Rocket.Chat.git
```
If you plan to contribute changes, fork the repository first and then clone your fork.
Navigate to the project directory and add the upstream repository to keep your fork synchronized with the original Rocket.Chat repository.
```
cd Rocket.Chat
git remote add upstream https://github.com/RocketChat/Rocket.Chat.git
```

Step 2: Install Node.js

Install Node Version Manager (nvm) to manage Node.js versions required for Rocket.Chat development.
```
brew install nvm
```
Verify that nvm version 0.39.2 or later is installed by running the command nvm --version in your terminal.

Next, identify the Node.js version required by the project:

cd Rocket.Chat
cat package.json | grep -A4 engines | grep node

Install the required version (replace x.x.x with the version shown above):
```
nvm install x.x.x
```
Check the node version installed by running:
```
node -v
```
Ensure the output matches the required version.

Step 3: Set up Deno

Rocket.Chat requires a specific version of Deno for certain development tools and scripts. Install the version defined in the project to ensure compatibility.

Confirm the Deno version required for your RocketChat project by running this command in the Rocket.Chat directory:
```
cat .tool-versions | grep deno
```
Install the required version of Deno (replace x.x.x with the version shown above):
```
curl -fsSL https://deno.land/install.sh | sh -s v1.37.1
```
For alternative installation methods, see the official Deno installation documentation.
Confirm you have the correct version installed by running:
```
deno --version
```
Ensure the installed version matches the project requirement and that Deno is available in your system PATH.

Step 4: Install Meteor

Rocket.Chat requires a specific Meteor version that matches your project release.

Depending on the Rocket.Chat version, you may need to install a specific Meteor version.
Version guidance:
Rocket.Chat 6.x and earlier → Meteor 2.x
Rocket.Chat 7.x and later → Meteor 3.x
Always rely on the .meteor/release file as the source of truth.

Check the .meteor/release file from the project root:
```
cat apps/meteor/.meteor/release
```
Install Meteor with the command below and replace x.x with the version identified above:
```
curl https://install.meteor.com/\?release\=x.x | sh
```
After installation, verify the version by running:
```
meteor --version
```
Ensure the installed version matches the project requirement.

Step 5: Run the Rocket.Chat project

Install all the required dependencies and packages for your project by running this command in your Rocket.Chat directory:
```
yarn
```
Run this command from the project root, otherwise, MongoDB will not start.
Build the application:
```
yarn build
```
You may see warnings about peer or transitive dependencies during the build. These are typically safe to ignore unless you are developing features that rely on them.
Start your development server.
For systems with 16 GB of memory or more, use this command:
```
yarn dev
```
For systems with less than 16 GB of memory, use:
```
yarn dsv
```
The initial build may take 10 minutes or longer. Subsequent builds are usually faster.
After the build completes, open:
```
http://localhost:3000
```
You should see your Rocket.Chat workspace running locally. If you encounter issues, see the troubleshooting guide.

Step 6: Edit Rocket.Chat files

You can use any code editor, but Visual Studio Code. is recommended for the best development experience.

Open the cloned Rocket.Chat repository in your editor.
As you make changes, the development server automatically rebuilds the application.
If the server stops after a change, restart it with:
```
yarn dsv
```

You are now ready to contribute. See the contribution guide for next steps.