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.

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.

npx turbo login --sso-team=<team-slug>