Turborepo (turbo) — CLI and pipeline configuration#

What it is#

Turborepo is Vercel’s monorepo task runner. It schedules package.json scripts across workspace packages with awareness of dependency topology, hashes every input to skip already-completed work, and ships local + remote caches so CI runners and teammates share build artefacts.

The CLI ships as the turbo npm package — a Rust binary distributed via npm. Pair it with pnpm workspaces (or npm/yarn/bun workspaces) for package management; turbo only handles task orchestration.

Install#

# In the monorepo root
npm install -D turbo
pnpm add -wD turbo            # -w for workspace root
yarn add -DW turbo
bun add -d turbo

# Optional global
npm install -g turbo

# Scaffold a fresh turborepo
npx create-turbo@latest

Output: turbo binary on PATH.

Day-to-day commands#

Common scenarios#

Build pipeline with cache#

// turbo.json
{
  "$schema": "https://turborepo.com/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    }
  }
}

turbo run build

Output (cold):

@my/ui:build:  ✓ built dist/ in 1.2s
@my/api:build: ✓ built dist/ in 0.8s
@my/web:build: ✓ built .next/ in 4.1s

Tasks:  3 successful, 3 total
Cached: 0 cached, 3 total
Time:   5.2s

Output (warm):

Tasks:  3 successful, 3 total
Cached: 3 cached, 3 total
Time:   142ms >>> FULL TURBO

Parallel dev mode#

{
  "tasks": {
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

turbo run dev

Output:

• Packages in scope: api, web, ui
• Running dev in 3 packages
web:dev: ready on http://localhost:3000
api:dev: ready on http://localhost:4000

persistent: true tells Turbo the task is long-running. cache: false skips cache replay. Each package’s dev script (vite, next dev, tsx watch, etc.) starts in parallel.

Remote cache setup#

turbo login                   # one-time browser-based login
turbo link                    # link this repo to a Vercel team

Output:

>>> Opening browser to log in
>>> Success! Turborepo CLI authorized for alice@example.com
✔ Linked to vercel/my-repo

~/.turbo/config.json now holds the token. Subsequent turbo run calls check remote cache first.

In CI:

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: my-team

Self-hosted alternative — the community turborepo-remote-cache proxy supports S3, R2, MinIO.

Filter to changed packages in CI#

turbo run build test lint --filter='[origin/main]'

Output:

• Packages changed since origin/main: @my/web, @my/ui
• Running build, test, lint in 2 packages
 Tasks:    6 successful, 6 total
 Time:     3.1s

Only builds packages touched (directly or via dependencies) by the current branch’s diff against main. Pair with actions/checkout fetch-depth: 0.

Pruning for Docker#

turbo prune --scope=@my/web --docker

Output:

Generating pruned monorepo for @my/web in ./out
 - Added @my/web
 - Added @my/ui
 - Added @my/utils

Outputs an out/ directory:

• out/json/ — minimal package.json per workspace package needed by @my/web
• out/full/ — actual source files
• out/pnpm-lock.yaml (or equivalent) — regenerated lockfile

Standard Dockerfile pattern:

FROM node:20-alpine AS pruner
WORKDIR /app
COPY . .
RUN npx turbo prune --scope=@my/web --docker

FROM node:20-alpine AS installer
WORKDIR /app
COPY --from=pruner /app/out/json/ .
RUN pnpm install --frozen-lockfile
COPY --from=pruner /app/out/full/ .
RUN pnpm turbo run build --filter=@my/web

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=installer /app/apps/web/.next/standalone ./
CMD ["node", "server.js"]

Multi-task invocation#

turbo run build test lint

Output:

• Packages in scope: api, web, ui
• Running build, test, lint in 3 packages
 Tasks:    9 successful, 9 total
 Cached:   6 cached, 9 total
 Time:     2.7s

Turbo plans the combined DAG:

• build tasks run first (respecting ^build)
• test tasks wait for their package’s build
• lint runs in parallel with everything

--concurrency=4 caps simultaneous work; default 10.

Generators#

npx turbo gen

Output:

? What generator would you like to run? › react-package
? Package name: new-pkg
✔ packages/new-pkg created

Interactive prompts driven by templates in turbo/generators/config.ts. Useful for “spin up a new internal package with the standard tsconfig + tsup setup”.

Useful flags#

Configuration#

turbo.json schema (v2)#

{
  "$schema": "https://turborepo.com/schema.json",
  "globalDependencies": [".env", "tsconfig.base.json"],
  "globalEnv": ["NODE_ENV", "CI"],
  "globalPassThroughEnv": ["GITHUB_TOKEN"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_API_URL"],
      "outputLogs": "new-only"
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**", "tests/**"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "deploy": {
      "dependsOn": ["build", "test"],
      "cache": false
    }
  }
}

Key fields:

• dependsOn — array of task names. ^build means “build of every dependency package”; bare build means “build of this package”.
• inputs — files that affect the cache hash. Narrow these to avoid spurious cache busts.
• outputs — files/directories the task produces. Cached as the task output.
• env — env vars that contribute to the cache hash AND are passed to the task.
• passThroughEnv — env vars passed to the task but NOT hashed.
• cache — true (default) or false. Disable for dev / deploy tasks.
• persistent — long-running tasks. Cannot have other tasks depend on them.
• outputLogs — "full", "hash-only", "new-only", "errors-only", "none".

Per-package turbo.json overrides#

A package can have its own turbo.json that extends the root:

// packages/web/turbo.json
{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**", "public/sw.js"]
    }
  }
}

Global env declarations#

Any env var your build reads must be declared, OR the cache will be wrong (stripped from the task env by default in v2).

{
  "globalEnv": ["NODE_ENV", "CI", "NEXT_PUBLIC_*"]
}

NEXT_PUBLIC_* wildcards match any var with that prefix.

Common pitfalls#

1. Missing inputs declaration — tsconfig change doesn’t invalidate cache. Add tsconfig/biome/eslint configs to globalDependencies or per-task inputs.
2. Undeclared env var — process.env.MY_VAR is undefined because Turbo strips unknown env. Add to env or passThroughEnv.
3. pipeline vs tasks (v1 vs v2) — pipeline was renamed to tasks in v2. Run npx @turbo/codemod migrate.
4. Remote cache misses on Node version — different Node versions produce different hashes. Pin Node in CI to match dev.
5. dependsOn direction confusion — ^build (with caret) is upstream deps; bare build is “this package’s build first”. Reading the docs slowly the first time saves grief.
6. outputs: [] for non-output tasks — tests/lint produce no artefacts you want to cache; explicitly set outputs: [] (Turbo will cache “task ran successfully” but no files).
7. Cache poisoning from PR forks — disable remote cache writes for PRs from forks. Use TURBO_CACHE_DIR=local for fork builds.
8. Daemon hangs — turbo daemon restart clears stuck state. Common after node_modules rebuilds.

See also#

• Packages: npm-turbo — full package reference, ecosystem, alternatives
• JavaScript: pnpm — recommended package manager companion
• Packages: npm-concurrently — for single-package script orchestration