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.
The turbo
package is a little shell that will install the proper @turborepo/*
packages.
Create turbo.json
In your root directory, create an empty file named turbo.json
.
This will hold the configuration for Turborepo in your project.
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
).
{
"$schema": "https://turborepo.org/schema.json",
"baseBranch": "origin/main"
}
Create a pipeline
In turbo.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.
{
"$schema": "https://turborepo.org/schema.json",
"baseBranch": "origin/main",
"pipeline": {
"build": {
"dependsOn": ["^build"],
// note: output globs are relative to each package's `package.json`
// (and not the monorepo root)
"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 relative to each packages's package.json
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 outputs folder for the build
task for each package. 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
Remote caching is available with zero configuration on Vercel.
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.
Note: When connecting to an sso-enabled Vercel team, you must provide your Team slug as an argument to npx turbo login
.
npx turbo login --sso-team=<team-slug>