Turborepo

Turborepo is a high-performance build system for JavaScript and TypeScript codebases, designed to scale build performance for large monorepos. Large projects at Netflix, AWS, and Disney use it, and it supports incremental builds backed by local and remote cache options.

Depot Cache provides a remote cache service that works with Turborepo, allowing you to incrementally cache and reuse parts of your builds. This cache is accessible from anywhere, both on your local machine and on CI/CD systems.

Configure Turborepo to use Depot Cache

Use Depot Cache with Turborepo from Depot's managed GitHub Actions runners, from your local machine, from any CI/CD system, or within containerized builds using Dockerfiles or Bake files.

From Depot-managed Actions runners

Depot GitHub Actions runners are pre-configured to use Depot Cache with Turborepo - each runner launches with a TURBO_API environment variable and includes the connection details for Depot Cache.

If you don't want Depot to set up the Turborepo environment variables on each runner, turn off Allow Actions jobs to automatically connect to Depot Cache in your organization settings page. You can manually configure Turborepo to use Depot Cache as described in the "Use Depot Cache from your local machine or any CI/CD system" section.

Use Depot Cache with Turborepo in depot/build-push-action

When using depot/build-push-action to build Docker images that contain Turborepo workspaces, your build needs access to Turborepo's remote cache credentials to benefit from caching.

These credentials aren't automatically available inside your Docker build environment. Unlike builds running directly on Depot-managed GitHub Actions runners, which have automatic access to Depot Cache environment variables, containerized builds execute in isolated VMs that require explicit configuration.

Follow these steps to pass your Turborepo credentials into your Docker build:

1. Create a GitHub Secret for your Depot token:

   • DEPOT_TOKEN

2. Configure your GitHub Action to pass the token as a secret:

- name: Build and push
  uses: depot/build-push-action@v1
  with:
    context: .
    file: ./Dockerfile
    push: true
    tags: your-image:tag
    secrets: |
      "TURBO_TOKEN=${{ secrets.DEPOT_TOKEN }}"

3. Update your Dockerfile to configure Depot Cache and mount the token as a secret:

# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Configure Depot Cache for Turborepo
ENV TURBO_API=https://cache.depot.dev
ENV TURBO_TEAM=your_org_id

# Mount the token secret
RUN --mount=type=secret,id=TURBO_TOKEN,env=TURBO_TOKEN \
    turbo build

Adding # syntax=docker/dockerfile:1 as the first line of your Dockerfile enables mounting secrets as environment variables.

Use Depot Cache from your local machine or any CI/CD system

To manually configure Turborepo to use Depot Cache, set three environment variables in your environment. These represent the Depot Cache service endpoint, your API token, and your Depot organization id:

export TURBO_API=https://cache.depot.dev
export TURBO_TOKEN=DEPOT_TOKEN
export TURBO_TEAM=DEPOT_ORG_ID

After you configure Turborepo to use Depot Cache, run your builds as you normally would. Turborepo automatically communicates with Depot Cache to fetch and reuse any stored build artifacts from your previous builds.

Use Depot Cache with Turborepo in Depot CLI

When building directly with Depot CLI, follow these steps:

1. Update your Dockerfile to configure Depot Cache and mount the token as a secret:

# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Configure Depot Cache for Turborepo
ENV TURBO_API=https://cache.depot.dev
ENV TURBO_TEAM=your_org_id

# Mount the token secret
RUN --mount=type=secret,id=TURBO_TOKEN,env=TURBO_TOKEN \
    turbo build

Adding # syntax=docker/dockerfile:1 as the first line of your Dockerfile enables mounting secrets as environment variables.

2. Build with Depot CLI:

export DEPOT_TOKEN=your_token
depot build --secret id=TURBO_TOKEN,env=DEPOT_TOKEN -t your-image:tag .

Or with Docker Buildx:

export DEPOT_TOKEN=your_token
docker buildx build --secret id=TURBO_TOKEN,env=DEPOT_TOKEN -t your-image:tag .

Use Depot Cache with Turborepo in Bake files

When using Bake files to build Docker images containing Turborepo workspaces, you can pass the token as a secret:

1. Define the configuration in your docker-bake.hcl file:

target "default" {
  context    = "."
  dockerfile = "Dockerfile"
  tags       = ["your-image:tag"]
  secret = [
    {
      type = "env"
      id   = "DEPOT_TOKEN"
    }
  ]
}

2. Update your Dockerfile to configure Depot Cache and mount the token as a secret:

# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Configure Depot Cache for Turborepo
ENV TURBO_API=https://cache.depot.dev
ENV TURBO_TEAM=your_org_id

# Mount the token secret
RUN --mount=type=secret,id=DEPOT_TOKEN,env=TURBO_TOKEN \
    turbo build

Adding # syntax=docker/dockerfile:1 as the first line of your Dockerfile enables mounting secrets as environment variables.

3. Run the build with depot bake:

export DEPOT_TOKEN=your_token
depot bake