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

Fork the official Rocket.Chat repository and clone it to your local machine:
```
git clone https://github.com/<your-username>/Rocket.Chat.git
```
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 higher 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 Deno version, replacing x.x.x with the version above:
```
curl -fsSL https://deno.land/install.sh | sh -s vx.x.x
```
For alternative installation methods, see the official Deno installation documentation.
Add Deno to your PATH permanently to make it available in future sessions:
```
echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
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 pins its Meteor version in the .meteor/release file.

From the Rocket.Chat directory, confirm the Meteor version required by your Rocket.Chat project:
```
cat apps/meteor/.meteor/release
```
Install Meteor, replacing x.x.x with the version from the previous step:
```
curl https://install.meteor.com/\?release\=x.x | sh
```
After installation, verify the version:
```
meteor --version
```
You should see the installed version displayed in your terminal.

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.

Documentation Index