Getting Started with Turborepo

Clone an example or starter monorepo

If you're starting a brand new monorepo, you can get started with a single command.

npx create-turbo@latest

Follow the prompts to bootstrap a brand new Turborepo.

To see more examples and starters, have a look at the examples directory on GitHub

Add Turborepo to your existing monorepo

Turborepo was designed to be incrementally adopted. Adding it to an existing monorepo takes only a few minutes.

Turborepo works with Yarn v1, NPM, and PNPM workspaces. The turbo CLI works on the following operating systems.

  • macOS darwin 64-bit (Intel), ARM 64-bit (Apple Silicon)
  • Linux 32-bit, 64-bit, ARM, ARM 64-bit, MIPS 64-bit Little Endian, PowerPC 64-bit Little Endian, IBM Z 64-bit Big Endian
  • Windows 32-bit, 64-bit, ARM 64-bit
  • FreeBSD 64-bit, ARM 64-bit
  • NetBSD AMD64
  • Android ARM 64-bit

Install turbo

Add turbo as a development dependency in the root of your project.

Yarn

yarn add turbo -W --dev

NPM

npm install turbo -D

PNPM

pnpm add turbo -w -D

The turbo package is a little shell that will install the proper @turborepo/* packages.

Add turbo to package.json

In your root package.json, add a key turbo. If your git repo's base branch is NOT origin/master then you need to specify a baseBranch too (for example, ours is set to origin/main).

{
"turbo": {
"baseBranch": "origin/main"
}
}

Create a pipeline

In your package.json, add the commands you want to "turbocharge" to your pipeline.

Your pipeline both defines the way in which your NPM package.json scripts relate to each other, and configures cache artifacts for those scripts. These relationships and cache settings are then fanned out and applied to all package tasks across your entire monorepo.

{
"turbo": {
"baseBranch": "origin/main",
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputs": [".next/**"]
},
"test": {
"dependsOn": ["^build"],
"outputs": []
},
"lint": {
"outputs": []
},
"dev": {
"cache": false
}
}
}
}

In the above example, the build and test tasks are dependent on their packages dependencies and devDependencies being built first, this is denoted with the ^ prefix.

For each script in each workspace's package.json, Turborepo will cache files outputted to dist/** and build/** folders by default if an override isn't added. Using the outputs array allows you to override the default cache folders, like in the example above, where the .next/** folder is selected to be the default cache folder for the build task. Turborepo will automatically record and cache logs to .turbo/turbo-<script>.log for you, so you don't ever need to specify that in the outputs array.

Finally, the dev task has its caching disabled using the cache key with a value of false.

See the Pipelines documentation for more details on how to configure your pipeline.

Edit .gitignore

Next, add .turbo to your .gitignore file. The CLI uses these folders for logs and certain task outputs.

+ .turbo

Make sure that your task artifacts (the files you want to be cached) are also ignored. As a rule, any files/folder that you want cached should be gitignored.

+ build/**
+ dist/**
+ .next/**

Ensure workspaces are configured

If you are moving from another tool to Yarn workspaces, be sure to also specify all workspaces in your package.json. The convention we follow is for applications to go into the /apps folder and packages to go in /packages folders.

{
+ "workspaces": [
+ "packages/*",
+ "apps/*"
+ ]
}

Now re-run your NPM client's install command just to be sure. You should be good to go now.

Run stuff!

To build with your freshly installed turbo, type the following:

Yarn

yarn turbo run build

Now run it again. Depending on your monorepo setup, some stuff might already be caching properly. If not, no worries! In the next sections, we'll discuss how turbo works, how scope works, and then how to get caching working after that.

Setup Remote Caching Beta

A major key đŸ”‘ to Turborepo's speed is that it is both lazy and efficient—it does the least amount of work possible and it tries to never redo work that's already been done before. At the moment, Turborepo caches your tasks on your local filesystem (i.e. "single-player mode," if you will). However, what if there was a way to take advantage of the computational work done by your teammates or your CI (i.e. "co-op multiplayer mode")? What if there was a way to teleport and share a single cache across machines? Almost like a "Dropbox" for your Turborepo cache.

Remote Caching has entered the chat.

Turborepo can use a technique known as Remote Caching to share cache artifacts across machines for an additional speed boost.

Remote Caching is a powerful feature of Turborepo, but with great power comes great responsibility. Make sure you are caching correctly first and double check handling of environment variables. Please also remember Turborepo treats logs as artifacts, so be aware of what you are printing to the console.

Link Your Turborepo to Your Remote Cache

As part of Turborepo's initial public launch, Vercel is offering free remote caching on all accounts with zero-configuration needed.

Using Remote Caching for Local development

If you want to link your local turborepo to your Remote Cache you do so by first authenticating the Turborepo CLI with your Vercel account:

npx turbo login

Next, you can link your turborepo to your remote cache by running the following command:

npx turbo link

Once enabled, make some changes to a package or application you are currently caching and run tasks against it with turbo run. Your cache artifacts will now be stored locally and in your Remote Cache. To verify that this worked, delete your local Turborepo cache:

rm -rf ./node_modules/.cache/turbo

Now run the same build again. If things are working properly, turbo should not execute tasks locally, but rather download both the logs and artifacts from your Remote Cache and replay them back to you.