Thanks for your interest in contributing to Turbo!
Important note: At the moment, Turbo is made up of two tools, Turborepo and Turbopack, built with different languages and toolchains. In the future, Turbo will become a single toolchain built on Rust and the Turbo engine. In the meantime, please follow the respective guide when contributing to each tool:
- Contributing to Turbo
- Rust
- cargo-groups (used to group crates into Turborepo-specific ones and Turbopack-specific ones)
Dependencies
-
Install turborepo crate build requirements
-
Run
pnpm installat root
Building
- Building
turboCLI: Inclirunmake turbo - Using
turboto buildturboCLI:./turbow.js
Turborepo uses reqwest, a Rust HTTP client, to make requests to the Turbo API. 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. Turborepo allows users to select which implementation they want with the native-tls
and rustls-tls features. By default, the native-tls feature is selected---this is done so that cargo build works
out of the box. If you wish to select rustls-tls, you may do so by passing --no-default-features --features rustls-tls
to the build command. This allows for us to build for more platforms, as native-tls is not supported everywhere.
Install dependencies
On macOS:
brew install jq zstdFirst: npm install -g turbo.
Then from the root directory, you can run:
- Go unit tests
pnpm test -- --filter=cli - A single Go unit test (see more in the Go docs)
cd cli && go test ./[path/to/package/]
- Rust unit tests (install
nextestfirst)You can also use the built incargo nextest run -p turborepo-lib --features rustls-tls
cargo testdirectly withcargo test -p turborepo-lib. - CLI Integration tests
pnpm test -- --filter=turborepo-tests-integration - A single Integration test
e.g to run everything in
tests/run_summary:Note: this is not through turbo, so you'll have to build turbo yourself first.# build first because the next command doesn't run through turbo pnpm -- turbo run build --filter=cli pnpm test -F turborepo-tests-integration -- "run_summary" - E2E test
pnpm -- turbo e2e --filter=cli
- Example tests
pnpm test -- --filter=turborepo-tests-examples -- <example-name> <packagemanager>
- Install
go install github.com/go-delve/delve/cmd/dlv@latest - In VS Code's "Run and Debug" tab, select
Build Basicto start debugging the initial launch ofturboagainst thebuildtarget of the Basic Example. This task is configured in launch.json.
Follow the instructions in the benchmark/README.md.
You might need to update packages/turbo in order to support a new platform. When you do that you will need to link the module in order to be able to continue working. As an example, with npm link:
cd ~/repos/vercel/turbo/packages/turbo
npm link
# Run your build, e.g. `go build ./cmd/turbo` if you're on the platform you're adding.
cd ~/repos/vercel/turbo/cli
go build ./cmd/turbo
# You can then run the basic example specifying the build asset path.
cd ~/repos/vercel/turbo/examples/basic
TURBO_BINARY_PATH=~/repos/vercel/turbo/cli/turbo.exe npm install
TURBO_BINARY_PATH=~/repos/vercel/turbo/cli/turbo.exe npm link turboIf you're using a different package manager replace npm accordingly.
Before releasing, it's recommended to test the turbo binary manually.
Here's a checklist of testing strategies to cover:
- Test
login,logout,login --sso-team,link,unlink - Test
prune(Noteturbohere is the unreleased turbo binary)pnpm dlx create-turbo@latest prune-test --package-manager pnpm && cd prune-testturbo --skip-infer prune docs && cd out && pnpm install --frozen-lockfileturbo --skip-infer build
- Test
--dry-runand--graph. - Test with and without daemon.
There are also multiple installation scenarios worth testing:
- Global-only.
turbois installed as global binary, no localturboin repository. - Local-only.
turbois installed as local binary, no globalturboin PATH. turbo` is invoked via a root package script. - Global + local.
turbois installed as global binary, and localturboin repository. Globalturbodelegates to localturbo
Here are a few repositories that you can test on:
These lists are by no means exhaustive. Feel free to add to them with other strategies.
See the publishing guide.
Creating a new release post can be done via a turborepo generator. Run the following command from anywhere within the repo:
turbo generate run "blog - release post"This will walk you through creating a new blog post from start to finish.
NOTE: If you would like to update the stats (github stars / npm downloads / time saved) for an existing blog post that has yet to be published (useful if time has passed since the blog post was created, and up to date stats are required before publishing) - run:
turbo generate run "blog - "blog - update release post stats"and choose the blog post you would like to update.
When adding a new crate to the repo, it is essential that it is included/excluded from the relevant workflows. This ensures that changes to the crate are tested by the correct workflows, but that they do not trigger unnecessary workflows as well.
First, determine whether the crate is for Turbopack or Turborepo. If it is for Turbopack, then the crate
should be added to the default-members key in the root Cargo.toml. If the crate is for Turborepo, the
crate must be added to the PATTERNS list in "Turborepo related changes" section of the test.yml
workflow file. It must also be excluded from the "Turbopack related changes" section of the
test.yml workflow file.
For instance, if we were adding a turborepo-foo crate, we would add the following patterns:
- name: Turbopack related changes
id: turbopack
uses: technote-space/get-diff-action@v6
with:
PATTERNS: |
pnpm-lock.yaml
package.json
crates/**
xtask/**
.cargo/**
rust-toolchain
!crates/turborepo/**
!crates/turborepo-lib/**
!crates/turborepo-ffi/**
!crates/turbo-updater/**
+ !crates/turborepo-foo/**
!**.md
!**.mdx
- name: Turborepo related changes
id: turborepo
uses: technote-space/get-diff-action@v6
with:
PATTERNS: |
pnpm-lock.yaml
package.json
crates/turborepo/**
crates/turborepo-lib/**
crates/turborepo-ffi/**
crates/turbo-updater/**
+ crates/turborepo-foo/**
.cargo/**
rust-toolchain
!**.md
!**.mdxThe crate must also be explicitly excluded from build commands
for Turbopack and included in build commands for Turborepo.
To do so, add a --exclude turborepo-foo flag to the Turbopack commands in
.cargo/config.toml such as tp-test, and add an -p turborepo-foo to the Turborepo
commands such as tr-test.
Finally, the crate must be added to the Turborepo section of CODEOWNERS:
# overrides for crates that are owned by turbo-oss
/crates/turborepo @vercel/turbo-oss
/crates/turborepo-ffi @vercel/turbo-oss
+ /crates/turborepo-foo @vercel/turbo-oss
/crates/turborepo-lib @vercel/turbo-oss
/crates/turborepo-scm @vercel/turbo-oss
/crates/turbo-updater @vercel/turbo-ossTurbopack uses Cargo workspaces in the Turbo monorepo. You'll find
several workspaces inside the crates/ directory. In order to run a particular
crate, you can use the cargo run -p [CRATE_NAME] command.
A high-level introduction to Turbopack's architecture, workspace crates, and Turbo engine (the turbo-tasks crates) is available at crates/turbopack/architecture.md.
Install cargo-nextest (https://nexte.st/):
cargo install cargo-nextest
Then, install dependencies for testcases:
pnpm install -r --side-effects-cache -C crates/turbopack/tests/node-file-trace
Run via:
cargo nextest runFor the test cases you need to run pnpm install to install some node_modules. See Troubleshooting for solutions to common problems.
You can also create a little demo app and run
cargo run -p node-file-trace -- print demo/index.jsSee the profiling docs for Turbopack for details.
See Troubleshooting.