Skip to content

Latest commit

 

History

History
146 lines (93 loc) · 5.16 KB

CONTRIBUTING.md

File metadata and controls

146 lines (93 loc) · 5.16 KB
Raw

Contributing to Turbo

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 Turborepo

Building Turborepo

Dependencies

  1. Install jq and sponge

    On macOS: brew install sponge jq

  2. Install turborepo crate build requirements

  3. Run pnpm install at root

Building

  • Building turbo CLI: In cli run make turbo
  • Using turbo to build turbo CLI: ./turbow.js

Running Turborepo Tests

Go Tests

From the root directory, you can

  • run unit tests with pnpm run --filter=cli test
  • run integration tests with pnpm run --filter=cli integration-tests
  • run e2e tests with pnpm run --filter=cli e2e

To run a single Go test, you can run go test ./[path/to/package/]. See more in the Go docs.

Rust Tests

The recommended way to run tests is: cargo nextest run -p turborepo-lib. You'll have to install it first.

You can also use the built in cargo test directly cargo test -p turborepo-lib.

Debugging Turborepo

  1. Install go install github.com/go-delve/delve/cmd/dlv@latest
  2. In VS Code's "Run and Debug" tab, select Build Basic to start debugging the initial launch of turbo against the build target of the Basic Example. This task is configured in launch.json.

Benchmarking Turborepo

  1. Build Turborepo as described above
  2. From the benchmark/ directory, run pnpm run benchmark.

Updating turbo

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 turbo

If you're using a different package manager replace npm accordingly.

Publishing turbo to the npm registry

All builds are handled by manually triggering the appropriate release GitHub workflow.

To manually run a release:

  1. brew install goreleaser
  2. Add GORELEASER_KEY env var with the GoReleaser Pro key (ask @turbo-oss to get access to the key)
  3. Update version.txt (do not commit this change to git manually)
  4. cd cli && make publish

Contributing to Turbopack

Turbopack 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. For example, to test the Next.js development server, run cargo run -p next-dev.

Turbopack Architecture

A high-level introduction to Turbopack's architecture, workspace crates, and Turbo engine (the turbo-tasks crates) is available at crates/turbopack/architecture.md.

Testing Turbopack

Install cargo-nextest (https://nexte.st/):

cargo install cargo-nextest

Run via:

cargo nextest run

For 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.js

Benchmarking Turbopack

See the benchmarking README for Turbopack for details.

Profiling Turbopack

See the profiling docs for Turbopack for details.

Troubleshooting

See Troubleshooting.