Using Turborepo with CircleCI

The following example shows how to use Turborepo with CircleCI (opens in a new tab).

For a given root package.json:

  "name": "my-turborepo",
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test"
  "devDependencies": {
    "turbo": "1.2.5"

And a turbo.json:

  "$schema": "",
  "pipeline": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**"],
      "dependsOn": ["^build"]
    "test": {
      "dependsOn": ["^build"]

Create a file called .circleci/config.yml in your repository with the following contents:

version: 2.1
  node: circleci/node@5.0.2
      - test
      - image: cimg/node:lts
      - checkout
      - node/install-packages
      - run:
        command: npm run build
      - run:
        command: npm run test

Remote Caching

To use Remote Caching with CircleCI, add the following environment variables to your CircleCI project to make them available to your turbo commands.

  • TURBO_TOKEN - The Bearer token to access the Remote Cache
  • TURBO_TEAM - The account to which the monorepo belongs

To use Vercel Remote Caching, you can get the value of these variables in a few steps:

  1. Create a Scoped Access Token to your account in the Vercel Dashboard (opens in a new tab)

Vercel Access Tokens

Copy the value to a safe place. You'll need it in a moment.

  1. Go to your CircleCI project settings and click on the Environment Variables tab. Create a new secret called TURBO_TOKEN and enter the value of your Scoped Access Token.

CircleCI Environment Variables CircleCI Create Environment Variables

  1. Make a second secret called TURBO_TEAM and enter the value of your team's Vercel URL without the Your Team URL can be found inside your team's general project settings from the dashboard.

    If you're using a Hobby Plan, you can use your username. Your username can be found in your Vercel Personal Account Settings (opens in a new tab)

Vercel Account Slug

  1. CircleCI automatically loads environment variables stored in project settings into the CI environment. No modifications are necessary for the CI file.