Thank you for your interest in contributing to Turborepo!

• General dependencies
• Optional dependencies
• Structure of the repository
• Building Turborepo
  • TLS Implementation
• Running tests
• Manually testing turbo
  • Repositories to test with
• Debugging tips
  • Links in error messages
  • Verbose logging
  • Crash logs
  • Terminal UI debugging
• Publishing turbo to the npm registry
• Contributing to examples
  • Contributing to an existing example
  • Philosophy for new examples
    • Designing a new example
  • Testing examples

You will need to have these dependencies installed on your machine to work on this repository:

• Rust (via rustup, which will automatically use the repository toolchain)
• Node.js v22
• pnpm v10
• protoc
• capnp

• Bun is required to build @turbo/gen (the turbo gen code generator). The @turbo/gen package is compiled into a standalone binary using bun build --compile.
• For running tests locally, jq and zstd are also required.
  • macOS: brew install jq zstd
  • Linux: sudo apt update && sudo apt install jq zstd
  • Windows: choco install jq zstandard
• On Linux, ensure LLD (LLVM Linker) is installed, as it's not installed by default on many Linux distributions (e.g. apt install lld).

In general, there are two major areas in the repository:

• The crates directory with the Rust code for the turbo binary
• The packages directory with JavaScript packages
• The examples directory with examples of how to use Turborepo with other tools and frameworks
• The docs directory with the documentation for Turborepo

1. Run pnpm install at the root of the repository
2. Run cargo build

Turborepo uses reqwest to make requests to the Remote Cache.

reqwest supports two TLS implementations: rustls and native-tls. rustls is a pure Rust implementation of TLS, while native-tls is a wrapper around OpenSSL. You may select which implementation you want with the native-tls and rustls-tls features.

By default, the rustls-tls feature is selected so that cargo build works out of the box. If you wish to select native-tls, you may do so by running cargo build --no-default-features --features native-tls.

Turborepo includes OpenTelemetry (OTel) support for exporting metrics in default builds.

If you need to build without OTel support, use:

cargo build -p turbo --no-default-features --features rustls-tls

experimentalObservability is still gated by futureFlags.experimentalObservability in turbo.json.

First, install Turborepo globally with your package manager of choice. For instance, with npm, npm install -g turbo. This will install the turbo binary in your system's PATH, making it globally available.

Now, from the root directory, you can run:

• Unit tests

  cargo test

• A module's unit tests

cargo test -p <module>

• Integration tests

  cargo test -p turbo

• A single integration test file

  cargo test -p turbo --test force_test

After building turbo, you can manually test turbo for the behaviors you're affecting with your changes. We recommend setting an alias to the built binary so you can call it with your alias.

alias devturbo='~/projects/turbo/target/debug/turbo'
devturbo run build --skip-infer

A non-exhaustive list of things to check on:

• Features related to your changes
• Test with and without daemon (daemon is deprecated for turbo run but still used by turbo watch)
• Installation scenarios
  • Global only. turbo is installed as global binary without a local turbo in repository.
  • Local only. turbo is installed as local binary without global turbo in PATH. turbo is invoked via a root package script.
  • Global and local. turbo is installed as global binary, and local turbo in repository. Global turbo delegates to local turbo

There are many open-source Turborepos out in the community that you can test with. A few are listed below:

• Next.js
• tldraw
• Tailwind CSS
• Vercel CLI
• This repository! Keep in mind that you'll be building and running turbo in the same repository, which can be confusing at times.

All output in Turborepo flows through turborepo-log. Use the following decision tree when adding new output:

To emit logs from a new area of the codebase, add a variant to the Subsystem enum in crates/turborepo-log/src/event.rs. The enum is #[non_exhaustive] so this is non-breaking. Each variant maps to a lowercase string via the Display impl.

Task Executor / Commands
        |
   GroupingLayer          <- per-task buffering (passthrough vs grouped)
        |
     Logger               <- broadcasts to all sinks
        |
   +---------+---------+
   |         |         |
Terminal   TuiSink   FileSink
 Sink

• TerminalSink: Owns line prefixing (ColorSelector, per-task line buffers), CI group markers, and color rendering.
• TuiSink: Routes task output to the TUI's task panes, normalizes \n to \r\n for the VT100 parser.
• FileSink / CollectorSink: Structured JSON capture.
• GroupingLayer: Manages per-task buffering. In passthrough mode (stream), events flow immediately. In grouped mode, events buffer per-task and flush atomically on task completion.

Many of Turborepo's error messages include links to information or documentation to help end users.

The base URL for the links can be set to a value of your choosing by providing a TURBO_SITE environment variable at compilation time.

TURBO_SITE="http://localhost:3000" cargo build

Verbose logging can be enabled by using the -v, -vv, or -vvv flag on your turbo command, depending on the level of logging you're looking for:

turbo build --vvv

In the event of a crash, Rust's crash logs will be written to your temp directory. When turbo crashes, the location of the crash log will be printed to the console.

The architecture of the Terminal UI makes for a tricky debugging experience. Because the UI writes to the console through stdout in a specific way, using println!() statements won't work as expected.

Instead, use eprintln!() to print to stdout and output stdout to a file:

# devturbo is an alias to the debug binary of `turbo` in this case
devturbo run build --ui=tui --skip-infer 2&> ~/tmp/logs.txt

See the publishing guide.

Contributing to examples helps the Turborepo community by showcasing how to use Turborepo in real-world scenarios with other tools and frameworks. They can be found in the examples directory of this repository.

The basic example is the default used by create-turbo.

For simplicity, each example is treated as a standalone "repository", separate from the rest of the repository, with its own dependencies, lockfile, turbo version, etc. You are able to run code and make code updates in an example without needing to install the dependencies of the rest of the repository.

To contribute to an existing example, create your code updates and submit a pull request to the repository. No special steps are required to contribute to an example.

Turborepo works with any framework, tool, or even language. Because of this, the community often expresses interest in creating new examples to showcase Turborepo working with other tooling.

However, we aim to have as few examples in the repository while still showcasing Turborepo's flexibility. By having fewer examples, the core team has a better chance to maintain the collection of examples, keeping them at a higher quality. The ecosystem evolves quickly, and keeping every example up-to-date for every tool requires a wealth of attention. Our goal is to balance the needs of the core team and the community together to keep the Turboverse in a healthy state.

Due to these considerations, we ask that you first open a Discussion before working on a new example for the repository. It's best to make sure ahead of time that the example you'd like to propose will be accepted. Once you have received approval, you can work on and create a pull request for your example.

Each example should have a specific focus when compared to the basic example. The goal is for an example to show how to use a singular, distinct technology's usage in a Turborepo.

You're encouraged to start with the basic example and add your specific tool of interest to it. Each example should have as few modifications to the basic example as possible required to showcase the tool or framework.

Key characteristics of a great example include:

• One technology added to the basic example
• An updated README at the root of the example directory. Make sure to include any steps required to run the example
• All tasks in turbo.json in the example run successfully without any code changes needed
• Works with every package manager listed in our Support Policy

Once you've created your example (with prior approval, as discussed above), you can submit a pull request to the repository.

To test out the experience of your example with create-turbo, run create-turbo with the --example flag pointed to a URL to your example's source code:

npx create-turbo@latest --example https://github.com/your-org/your-repo/tree/your-branch/...

This will allow you to use the example as a user would.