# What Is the Role of Turbo in the Rocket.Chat Build Process?

> Discover how Turbo optimizes the Rocket.Chat build process. Learn about its role in task running, intelligent caching, and orchestrating the monorepo build pipeline for faster development.

- Repository: [Rocket.Chat/Rocket.Chat](https://github.com/RocketChat/Rocket.Chat)
- Tags: internals
- Published: 2026-06-18

---

**Turbo (TurboRepo) serves as the central task-runner and intelligent caching layer that orchestrates the monorepo-wide build pipeline for Rocket.Chat, coordinating dependency ordering, parallel execution, and artifact caching across development and CI environments.**

Rocket.Chat leverages TurboRepo to manage its complex monorepo architecture, where multiple packages—including the core Meteor application, Apps Engine, and various microservices—must build in the correct sequence. By defining explicit task pipelines and maintaining granular cache outputs, Turbo eliminates redundant compilation work and ensures that developers and continuous integration pipelines execute only the tasks that have actually changed.

## Orchestrating the Monorepo Pipeline

At its core, Turbo functions as the **centralized task runner** that replaces traditional npm scripts with an intelligent dependency graph. According to the [`package.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/package.json) scripts section, Turbo commands such as `yarn turbo run build`, `yarn turbo run dev`, and `yarn turbo run ms` initiate complex workflows that span multiple packages.

The pipeline configuration resides in the root **[`turbo.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/turbo.json)**, which declares the explicit dependency relationships between tasks. When you execute a command, Turbo automatically determines the correct build order, ensuring that shared libraries compile before dependent applications without manual intervention. This dependency ordering is crucial for Rocket.Chat’s architecture, where the Apps Engine and core Meteor client rely on shared underlying packages.

### Parallel Execution and Task Filtering

Turbo employs parallel execution across the monorepo’s packages while respecting the dependency graph. For example, running `yarn turbo run dev --filter=@rocket.chat/meteor...` starts the development server for the Meteor client while simultaneously building only the upstream packages that have changed. This `--filter` syntax allows developers to target specific workspaces, reducing startup time significantly during iterative development.

## Intelligent Caching Strategy

Turbo’s caching mechanism is the primary driver of build performance in Rocket.Chat. The system creates a local cache directory **`.turbo/`** (which is explicitly ignored in `.gitignore` to prevent committed artifacts) that stores compiled outputs, test results, and other task outputs. When a task is re-run, Turbo checks the cache first; if the inputs—including source files, environment variables, and dependency hashes—remain unchanged, it restores the output instantly rather than re-executing the build.

### Local Cache Storage

The `.turbo/` directory sits at the repository root and accumulates cached artifacts from all packages. Individual packages can extend the caching behavior by adding their own **[`turbo.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/turbo.json)** files. For instance, the Apps Engine package at [`packages/apps-engine/turbo.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/packages/apps-engine/turbo.json) declares additional output directories to ensure that generated Deno bundles and other transpiled assets are properly cached alongside the standard build outputs.

### CI Cache Restoration and Invalidation

In continuous integration, the **[`.github/workflows/ci.yml`](https://github.com/RocketChat/Rocket.Chat/blob/main/.github/workflows/ci.yml)** pipeline implements sophisticated cache management to share Turbo artifacts across workflow runs. The CI system computes a `PACKAGES_HASH` by hashing `yarn.lock`, [`.yarnrc.yml`](https://github.com/RocketChat/Rocket.Chat/blob/main/.yarnrc.yml), [`package.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/package.json), and the root **[`turbo.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/turbo.json)**. This hash determines the cache key, ensuring that the cache is invalidated only when package dependencies or pipeline configurations change.

```yaml

# .github/workflows/ci.yml – store Turbo cache

- name: Store turbo build
  uses: actions/cache@v3
  with:
    path: .turbo/cache
    key: ${{ runner.os }}-turbo-${{ env.PACKAGES_HASH }}

```

By restoring the `.turbo/cache` directory at the start of each run and storing it upon completion, Rocket.Chat achieves near-instantaneous rebuilds in CI when code changes do not affect the dependency tree, dramatically reducing pipeline durations.

## Essential Turbo Commands for Rocket.Chat Development

The following commands represent the primary interface between developers and the Rocket.Chat build system, as defined in the repository’s [`package.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/package.json):

```bash

# Execute the full production build pipeline for all packages

yarn turbo run build

# Start the development server for the Meteor client with filtered dependencies

yarn turbo run dev --filter=@rocket.chat/meteor...

# Spin up the microservices environment (e.g., Rocket.Chat services)

yarn turbo run ms --env-mode=loose

# Run linting across the entire monorepo

yarn turbo run lint

# Execute unit tests with parallelization

yarn turbo run testunit

```

The **`yarn turbo run ms`** command deserves particular attention; as documented in [`HISTORY.md`](https://github.com/RocketChat/Rocket.Chat/blob/main/HISTORY.md), this command initializes the microservices architecture, allowing developers to run the distributed service layer locally with the same dependency awareness and caching benefits as the monolithic build.

## Package-Level Turbo Configuration

While the root [`turbo.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/turbo.json) defines the global pipeline, individual packages can extend these definitions. The Apps Engine package demonstrates this pattern by maintaining its own **[`packages/apps-engine/turbo.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/packages/apps-engine/turbo.json)** to declare package-specific outputs. This ensures that when the Apps Engine compiles Deno-compatible bundles or generates migration artifacts, those outputs are captured in the Turborepo cache and preserved across builds.

This hierarchical configuration allows Rocket.Chat to scale its build definitions organically; new services can add specialized caching rules without modifying the root configuration, maintaining clean separation of concerns while still benefiting from the centralized task runner.

## Summary

- **Turbo coordinates the monorepo build pipeline** by defining task dependencies in [`turbo.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/turbo.json) and executing them in the correct order with parallelization.
- **Intelligent caching** via the `.turbo/` directory eliminates redundant compilation by restoring artifacts when inputs remain unchanged, with cache invalidation based on hashes of `yarn.lock`, [`package.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/package.json), and configuration files.
- **CI integration** in [`.github/workflows/ci.yml`](https://github.com/RocketChat/Rocket.Chat/blob/main/.github/workflows/ci.yml) persists the Turbo cache across workflow runs, using composite keys to ensure cache validity.
- **Package-level extensions** allow specific modules like the Apps Engine to define additional cached outputs through local [`turbo.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/turbo.json) files.
- **Developer commands** such as `yarn turbo run build`, `yarn turbo run dev`, and `yarn turbo run ms` provide a unified interface for building, developing, and running the microservices architecture.

## Frequently Asked Questions

### How does Turbo determine which packages to rebuild in Rocket.Chat?

Turbo calculates a hash based on the source files, environment variables, and dependencies of each task defined in [`turbo.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/turbo.json). If the hash matches a previous run and the outputs exist in the `.turbo/` cache, Turbo restores the cached results instead of rebuilding. Changes to `yarn.lock`, [`package.json`](https://github.com/RocketChat/Rocket.Chat/blob/main/package.json), or the pipeline configuration itself will invalidate the cache and trigger fresh builds for affected packages.

### Can I run only the Rocket.Chat Meteor app without building all dependencies?

Yes, you can use the `--filter` flag to target specific packages. For example, `yarn turbo run dev --filter=@rocket.chat/meteor...` tells Turbo to run the development server for the Meteor client and only build the upstream packages in its dependency graph that have changed or are not cached. This significantly reduces startup time compared to building the entire monorepo.

### What is the purpose of the `yarn turbo run ms` command?

The `ms` command initializes the **microservices environment** for Rocket.Chat. As implemented in the repository’s scripts, this command leverages Turbo’s pipeline to start the various distributed services (such as account-service, authorization-service, etc.) with proper dependency ordering. The `--env-mode=loose` flag allows environment variables to be passed through to the services, making it suitable for local development of Rocket.Chat’s service-oriented architecture.

### Where does Turbo store its build cache in Rocket.Chat?

Turbo stores build artifacts in the **`.turbo/`** directory at the repository root. This directory is listed in `.gitignore` to prevent cached files from being committed to version control. In CI environments, GitHub Actions persists this directory between workflow runs using the `actions/cache` action, with the cache path set to `.turbo/cache` and keys derived from package hash files.