Turborepo caching - Namespace Documentation

Turborepo is a popular build system optimized for Javascript and TypeScript. Namespace has first-class support for high-performance turborepo caching. Caches are backed by storage systems running alongside your jobs, for maximum network bandwidth and storage performance.

Getting started with GitHub Actions

To use turborepo caching, you can simply add Namespace’s setup-turbocache to your workspace:

jobs:
  build:
    runs-on: namespace-profile-default
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up caching
        uses: namespace-actions/setup-turbocache@v0
      - name: Go turbo
        run: turbo build

Configuration

By default, caching is performed to a single shared storage main. But you can isolate your caches by specifying a separate team (in turbo parlance):

jobs:
  build:
    runs-on: namespace-profile-default
    steps:
      - name: Checkout code
        uses: actions/checkout@4
      - name: Set up caching
        uses: namespace-actions/setup-turbocache@v0
        with: 
          team: secondary
      - name: Go turbo
        run: turbo build

Using from your local workstation

You can also use Namespace’s turborepo cache from your local machine. Since the cache is shared, local builds benefit from artifacts already cached by CI — and vice versa. First, install the Namespace CLI. Then use the CLI to configure your shell:

export $(nsc cache turborepo setup --team main)
turbo build

nsc cache turborepo setup issues a short-lived cache token and prints the environment variables that turbo needs:

Output

TURBO_API=https://turbo.cache.namespaceapi.com
TURBO_TEAM=main
TURBO_TOKEN=nsct_...

--team can be any string, and can be used to split caches between different projects. Run nsc cache turborepo list to see the teams that already hold cached artifacts. Alternatively, you can run:

turbo login --manual

This will ask for the same values, but stores the URL and team in your turbo.json.

Read-only access

Pass --read-only to consume the cache without publishing to it. This sets TURBO_CACHE=local:rw,remote:r, so turbo still writes to your local cache but never uploads:

export $(nsc cache turborepo setup --team main --read-only)

--read-only configures the turbo client. To also enforce read-only access on the server side — for example for builds of untrusted pull requests — run the setup command with a token that only carries the read action:

nsc token create \
  --name "turborepo-cache-read-only" \
  --grant '{"resource_type":"cache/turborepo","resource_id":"*","actions":["read"]}'

Point the CLI at that token with nsc cache turborepo setup --token <path>, or set NSC_TOKEN_FILE when the token was written with --token_file. See Permissions for the full list of cache/turborepo actions, and nsc token create for expiration and scoping options.

Getting started with Buildkite

In Buildkite, run the setup command at the start of the step and export the configuration into the step’s shell:

steps:
  - label: "Build"
    commands:
      - export $(nsc cache turborepo setup --team main --mask-buildkite)
      - turbo build

--mask-buildkite registers the issued token with the Buildkite redactor, so it is redacted from job logs. It requires buildkite-agent on PATH, which is the case on Namespace-managed Buildkite agents.

Usage

Namespace accounts Turborepo cache usage in two categories:

Turborepo cache storage
Turborepo cache reads

For detailed billing information for each item as well as included amounts in your plans, visit the pricing page.

​Getting started with GitHub Actions

​Configuration

​Using from your local workstation

​Read-only access

​Getting started with Buildkite

​Usage