Turborepo

Turborepo is a high-performance build system for JavaScript and TypeScript codebases, and is designed around scaling build performance for large monorepos. It is used by large projects at Netflix, AWS, and Disney, and supports incremental builds backed by local and remote cache options.

Depot Cache provides a remote cache service that can be used 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.

Configuring Turborepo to use Depot Cache

Depot Cache can be used with Turborepo from Depot's managed GitHub Actions runners, from your local machine, or from any CI/CD system.

From Depot-managed Actions runners

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

If this automatic configuration is incompatible with your specific setup, you can disable automatic configuration in your organization settings page and manually configure Turborepo to use Depot Cache as described below.

From your local machine or any CI/CD system

To manually configure Turborepo to use Depot Cache, you will need to 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

Once Turborepo is configured to use Depot Cache, you can then run your builds as you normally would. Turborepo will automatically communicate with Depot Cache to fetch and reuse any stored build artifacts from your previous builds.

Using 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 are not 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 securely pass your Turborepo credentials into your Docker build:

1. Create GitHub Secrets for your Turborepo cache variables:

   • TURBO_API
   • TURBO_TOKEN
   • TURBO_TEAM

2. Configure your GitHub Action to pass secrets to the container build:

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

3. Update your Dockerfile to mount the secrets as environment variables:

# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Mount secrets with IDs matching the environment variable names
RUN --mount=type=secret,id=TURBO_API,env=TURBO_API \
    --mount=type=secret,id=TURBO_TOKEN,env=TURBO_TOKEN \
    --mount=type=secret,id=TURBO_TEAM,env=TURBO_TEAM \
    turbo build

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