Turborepo Skill

intent

Turborepo is a build system for JavaScript/TypeScript monorepos that caches task outputs and runs tasks in parallel based on dependency graphs. use this skill when configuring tasks, creating packages, setting up monorepos, sharing code between apps, running changed/affected packages, debugging cache, or structuring apps/packages directories. turborepo lets you define what tasks depend on what, which outputs to cache, which environment variables matter, and how to parallelize work without redundant builds.

inputs

required context

• monorepo root directory: where turbo.json lives. turborepo expects turbo.json at the repo root and package.json files in each package.
• package.json files: each package (apps/, packages/) needs its own package.json with scripts defined. root package.json should only delegate to turbo run, not contain task logic.
• turbo.json configuration: root task definitions, dependsOn relationships, cache outputs, environment variables, global settings.

external connections

• git repository: turborepo uses git to detect changed files (--affected flag). requires git initialized and remote configured (typically origin/main as default branch).
• remote cache (optional): turborepo can push/pull cache from Vercel or custom backends. requires TURBO_TOKEN and TURBO_TEAM env vars (for Vercel) or custom remoteCache config in turbo.json.
• CI environment: GitHub Actions, GitLab CI, CircleCI, etc. turborepo infers CI context and skips cache on local runs by default.
• framework tooling: Next.js, Vite, tsc, Vitest, ESLint, etc. turborepo orchestrates these but does not replace them. your packages' build scripts invoke these tools.

setup guidance

minimum viable turbo.json:

{
  "$schema": "https://turborepo.org/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "lint": {},
    "test": {
      "dependsOn": ["build"]
    }
  }
}

enable remote cache (Vercel):

• set TURBO_TOKEN env var (from turbo.dev login)
• set TURBO_TEAM env var (your team slug)
• turbo will auto-push to and pull from Vercel remote cache

enable remote cache (custom):

{
  "remoteCache": {
    "apiUrl": "https://my-cache.example.com",
    "signature": true
  }
}

git setup:

• turbo uses git to compare branches. requires git initialized and default branch configured (usually origin/main).
• for --affected to work, git must know what changed relative to the default branch. if git is missing, --affected fails.

procedure

step 1: define package structure

input: desired monorepo layout (which packages are apps, which are libraries/shared code).

output: directory structure with each package containing package.json and source files.

1. create apps/ directory for applications (Next.js, Remix, Express servers, etc.).
2. create packages/ directory for shared libraries (UI components, utilities, types, validators, etc.).
3. create a package.json in each app and package with a name (e.g., "name": "@repo/web", "name": "@repo/ui").
4. add scripts to each package's package.json (e.g., "build": "tsc", "lint": "eslint .", "test": "vitest").
5. do NOT put task logic in root package.json. only add delegation scripts like "build": "turbo run build".

example structure:

my-monorepo/
├── turbo.json
├── package.json (root - no task logic)
├── apps/
│   ├── web/
│   │   ├── package.json (scripts: build, dev, test, lint)
│   │   └── src/
│   ├── api/
│   │   ├── package.json (scripts: build, test, lint)
│   │   └── src/
├── packages/
│   ├── ui/
│   │   ├── package.json (scripts: build, lint)
│   │   └── src/
│   ├── types/
│   │   ├── package.json (scripts: build)
│   │   └── src/

step 2: declare dependencies between packages

input: which packages import from which other packages.

output: package.json dependency declarations and turbo.json dependsOn rules.

1. in each package's package.json, add workspace dependencies to other packages. example:

   {
     "dependencies": {
       "@repo/types": "workspace:*",
       "@repo/ui": "workspace:*"
     }
   }
   

2. use workspace:* protocol (pnpm, Yarn modern, bun) or just "*" (npm with workspaces field in root package.json).
3. verify all code dependencies are declared in package.json. if a package imports from another but doesn't declare it, turbo's ^build won't order tasks correctly.

example: if apps/web imports from @repo/types and @repo/ui, it must declare both:

{
  "name": "@repo/web",
  "dependencies": {
    "@repo/types": "workspace:*",
    "@repo/ui": "workspace:*"
  }
}

step 3: configure root turbo.json tasks

input: which tasks exist in packages and what their dependencies are.

output: turbo.json with task definitions, dependsOn relationships, outputs, and environment variables.

1. define a tasks object with one entry per task type (build, lint, test, dev, etc.).
2. for build-like tasks (compile, type-check, bundle), add dependsOn: ["^build"] to run builds in dependencies first.
3. for test/lint tasks that depend on built code, add dependsOn: ["build"] or dependsOn: ["^build"] as needed.
4. add outputs key for any task that writes files to disk (build, generate, etc.). this tells turbo what to cache.
5. add env key if the task reads environment variables (e.g., API_URL, DATABASE_URL). turborepo hashes these to invalidate cache.
6. add inputs key if the task should re-run when specific files change (e.g., .env, turbo.json).
7. set cache: false and persistent: true for long-running tasks (dev servers, watchers).

example turbo.json:

{
  "$schema": "https://turborepo.org/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["NODE_ENV"]
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

step 4: set up environment variables

input: which environment variables each task needs to read.

output: env keys in task definitions and/or global globalEnv.

1. for variables shared across all (or most) tasks, add globalEnv at root level.
2. for task-specific variables, add env key in the task definition.
3. if tasks read .env files, add inputs: ["$TURBO_DEFAULT$", ".env", ".env.*"] to invalidate cache when those files change. (turborepo does not load .env files; your framework does. but turbo needs to know about changes.)
4. avoid root .env files in monorepos. instead, create .env files in specific packages that need them.
5. for CI variables (e.g., GITHUB_TOKEN), use globalPassThroughEnv to pass them without invalidating cache unnecessarily.

example:

{
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "env": ["API_URL", "DATABASE_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.local"]
    }
  }
}

step 5: filter and run tasks

input: which packages to run tasks in (all, changed, specific names, etc.).

output: task execution with correct filtering and caching.

1. to run all packages: turbo run build.
2. to run only changed packages and their dependents: turbo run build --affected.
3. to run a specific package: turbo run build --filter=web.
4. to run a package and its dependents: turbo run build --filter=...web.
5. to run a package and its dependencies: turbo run build --filter=web....
6. in package.json scripts, always use turbo run (not shorthand turbo). in CI pipelines, always use turbo run.
7. in interactive terminal use, turbo build shorthand is acceptable but turbo run build is more explicit.

examples:

# all packages
turbo run build

# changed packages + dependents
turbo run build --affected

# specific package
turbo run build --filter=@repo/web

# package + dependencies
turbo run build --filter=@repo/web...

# package + dependents
turbo run build --filter=...@repo/web

step 6: debug and optimize cache

input: cache misses, unexpected rebuilds, or performance issues.

output: corrected turbo.json or resolved cache problems.

1. run turbo run build --dry to see what turbo plans to run without executing.
2. run turbo run build --summarize to see cache hit/miss reasons.
3. if a task runs even when nothing changed, check:
   • is outputs key missing or wrong? (file-producing tasks must declare outputs)
   • is env missing a variable that affects the build?
   • is inputs missing a file that should invalidate cache (e.g., .env, package.json)?
   • is globalDependencies too broad, invalidating all tasks?
4. if cache hits but output is wrong, check environment variables are listed in env.
5. to skip cache for a single run: turbo run build --force.
6. to disable cache for a task entirely: set cache: false in turbo.json.

step 7: set up CI integration

input: CI provider (GitHub Actions, GitLab CI, etc.) and whether to use remote cache.

output: CI workflow that runs turbo with --affected and remote cache.

1. in CI, use turbo run build --affected to run only changed packages.
2. enable remote cache by setting TURBO_TOKEN and TURBO_TEAM (or custom remoteCache config).
3. CI variables (e.g., CI=true) are auto-detected by turbo and skip local caching.
4. for GitHub Actions, create .github/workflows/ci.yml:

   name: CI
   on: [push, pull_request]
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-node@v4
           with:
             node-version: 20
         - run: npm ci
         - run: turbo run build --affected
         - run: turbo run lint --affected
         - run: turbo run test --affected
   

5. to skip the entire CI step if no relevant files changed, use turbo-ignore (turbo's built-in tool for detecting which packages changed).

step 8: enforce package boundaries (optional)

input: which packages should be allowed to import from which other packages (architectural rules).

output: boundary configuration in turbo.json and CI checks.

1. add a boundaries key to root turbo.json with rules.
2. tag packages in their package.json (e.g., "turbo": { "tags": ["scope:ui", "type:library"] }).
3. define rules (e.g., "ui packages cannot import from api packages").
4. run turbo boundaries in CI to check for violations.

example:

{
  "boundaries": {
    "rules": [
      {
        "from": ["tag:scope:api"],
        "to": ["tag:scope:ui"],
        "allow": false
      }
    ]
  }
}

decision points

if your task produces files on disk

then add an outputs key listing the files or globs (e.g., "outputs": ["dist/**"]). without this, turbo caches nothing and re-runs the task every time.

else (task only outputs to stdout or is a check/linter), leave outputs empty or omit it.

if your task reads environment variables

then add an env key listing the variables (e.g., "env": ["API_URL", "DATABASE_URL"]). turborepo hashes these to invalidate cache when they change.

else (task is deterministic and doesn't read env), omit env.

if your task depends on built code from other packages

then add dependsOn: ["^build"] to run builds in dependencies first.

else (task is standalone or only needs source), omit or use dependsOn: [].

if you want to run only changed packages in CI

then use turbo run build --affected. turborepo detects which files changed relative to the default branch and runs only affected packages plus their dependents.

else (run everything), use turbo run build with no filter.

if your task should not be cached (e.g., dev servers, watchers)

then set cache: false and persistent: true. turborepo will not cache the output and will keep the process running.

else (cacheable task), omit these keys (defaults are cache: true, persistent: false).

if you have a root .env file that affects all packages

then move variables to package-specific .env files and remove the root .env. if you must share variables, use globalEnv to be explicit.

else (each package has its own .env as needed), no change needed.

if a task bypasses turbo (e.g., cd apps/web && npm run build && cd ../api && npm run build)

then refactor to use turbo run with proper dependsOn relationships. turbo orchestrates the order; you don't need manual sequencing.

else (task delegates to turbo), no change needed.

if you're using the turbo shorthand in package.json or CI scripts

then change to turbo run <task>. the shorthand is only for interactive terminal commands.

else (using turbo run in scripts), no change needed.

if you have multiple packages with different task configurations

then use Package Configurations (create a turbo.json in each package) instead of cluttering root turbo.json with package#task overrides.

else (all packages share the same task config), keep config in root turbo.json.

if you need to run tasks in parallel despite dependencies

then use a Transit Node pattern: define an empty task (e.g., transit) with dependsOn: ["^transit"] and have other tasks depend on it. this creates dependency relationships without requiring built outputs.

else (standard sequential execution), use dependsOn: ["^build"] directly.

if you're in a CI environment and need to pass CI variables (e.g., GITHUB_TOKEN)

then add them to globalPassThroughEnv so they're passed through without invalidating cache unnecessarily.

else (no special CI variables), omit this key.

output contract

success looks like:

1. turbo.json is valid JSON with no syntax errors. it must contain at minimum a tasks object with task definitions.

2. all packages have package.json files with:

   • a name field (e.g., "@repo/web")
   • a scripts field with task definitions (e.g., "build": "tsc", "lint": "eslint .")
   • workspace dependencies declared for any package they import from (e.g., "dependencies": { "@repo/ui": "workspace:*" })

3. root package.json contains only:

   • workspace configuration (e.g., "workspaces": ["apps/*", "packages/*"])
   • repo-level devDependencies (e.g., turbo, linters, formatters)
   • delegation scripts that call turbo run <task> (e.g., "build": "turbo run build")

4. turbo.json task definitions include:

   • dependsOn for build tasks (e.g., ["^build"]) or empty array/omitted if standalone
   • outputs for file-producing tasks (globs like ["dist/**"])
   • env if the task reads environment variables
   • inputs if the task should re-run when specific files change
   • cache: false and persistent: true for long-running tasks only

5. environment variables are declared in env or globalEnv keys, not left implicit. .env files are in individual packages, not at the root.

6. filtering works correctly: turbo run build --affected detects only changed packages and their dependents. turbo run build --filter=web runs only the specified package.

7. cache is working: running the same task twice produces "cache hit" output (visible with --summarize). removing cache with --force and re-running completes successfully.

8. CI integration is set up with remote cache enabled (if using Vercel or custom backend) and --affected flag used to optimize CI runs.

9. no task logic in root package.json. all scripts delegate to turbo (e.g., "build": "turbo run build").

10. no relative paths (../) in turbo.json inputs/outputs. use $TURBO_ROOT$ instead.

outcome signal

the user knows the skill worked when:

1. turbo run build completes successfully and outputs "cache hit" on the second run without changing any code.

2. turbo run build --affected runs only the packages that changed plus their dependents, not the entire monorepo. visible in the output log showing filtered package list.

3. turbo run lint && turbo run test execute in parallel (if configured to do so) and complete faster than sequential runs.

4. environment variable changes (e.g., modifying API_URL in .env) cause the cache to invalidate and tasks to re-run. visible with --summarize showing cache miss reason is env change.

5. CI passes with --affected flag and completes faster than running all tasks. remote cache is populated (visible in Vercel dashboard or custom cache logs).

6. turbo boundaries check (if configured) catches invalid imports between packages and fails CI.

7. no "task not found" errors when running turbo run <taskname>. all packages have the script defined in their package.json.

8. dev servers and watchers don't hang when using cache: false and persistent: true. processes stay alive and respond to file changes.

9. --filter syntax works intuitively: --filter=web runs web, --filter=...web runs web and its dependents, --filter=web... runs web and its dependencies.

10. monorepo structure is clear: apps/ contains applications, packages/ contains libraries, no shared code inside an app, no circular imports.