Configuring turbo.json

Hướng dẫn chi tiết cấu hình turbo.json trong Turborepo — tasks, caching, global options, environment variables, remote cache, boundaries và experimental observability.

turbo.json là file cấu hình trung tâm của Turborepo, đặt tại thư mục gốc của monorepo. Nó định nghĩa task graph, caching behavior, environment variables và các global options.

Hỗ trợ cả .jsonc (thêm comment).

1. Global Options

Các option áp dụng cho toàn bộ monorepo:

extends

Kế thừa cấu hình từ root turbo.json:

./apps/web/turbo.json

{
  "extends": ["//"]
}

"//" = reference root. Có thể extends từ nhiều package khác: ["//", "shared-config"].

globalDependencies

Glob patterns — file nào thay đổi thì all tasks miss cache:

./turbo.json

{
  "globalDependencies": ["tsconfig.json", ".env"]
}

Mặc định root package.json + lockfile luôn được include.

globalEnv

Env vars ảnh hưởng đến hash của tất cả tasks:

./turbo.json

{
  "globalEnv": ["GITHUB_TOKEN", "NODE_ENV"]
}

globalPassThroughEnv

Cho phép env vars đi qua task runtime, nhưng không ảnh hưởng cache hash:

./turbo.json

{
  "globalPassThroughEnv": ["AWS_SECRET_KEY"]
}

ui

Chọn terminal UI:

./turbo.json

{
  "ui": "stream"
}

"tui" — interactive, xem từng log
"stream" — log xuất trực tiếp (mặc định)

concurrency

Giới hạn số tasks chạy song song:

./turbo.json

{
  "concurrency": 4
}

Số nguyên ≥ 1
Percentage: "50%" — dùng 50% số cores
1 — chạy tuần tự

cacheDir

Thư mục lưu cache local:

./turbo.json

{
  "cacheDir": ".turbo/cache"
}

cacheMaxAge

Tự động xóa cache entries cũ theo thời gian:

./turbo.json

{
  "cacheMaxAge": "7d"
}

Hỗ trợ: 30s, 5m, 24h, 7d, 2w. Mặc định "0" (tắt).

cacheMaxSize

Giới hạn dung lượng cache local:

./turbo.json

{
  "cacheMaxSize": "10GB"
}

Hỗ trợ: 500MB, 10GB, 1TB. Chạy sau age-based eviction.

2. Tasks

dependsOn

Định nghĩa dependency giữa các tasks — ba loại:

Dependency relationship (^ prefix — chờ task build của dependencies xong trước):

./turbo.json

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

Same-package relationship (chờ task khác trong cùng package):

./turbo.json

{
  "tasks": {
    "test": {
      "dependsOn": ["lint", "build"]
    }
  }
}

Arbitrary task relationship (giữa các package cụ thể):

./turbo.json

{
  "tasks": {
    "web#lint": {
      "dependsOn": ["utils#build"]
    }
  }
}

env

Khai báo env vars ảnh hưởng cache hash của task:

./turbo.json

{
  "tasks": {
    "build": {
      "env": ["DATABASE_URL", "API_KEY"]
    }
  }
}

Hỗ trợ wildcards:

./turbo.json

{
  "tasks": {
    "build": {
      "env": ["MY_API_*"]
    }
  }
}

Hỗ trợ negation:

./turbo.json

{
  "tasks": {
    "build": {
      "env": ["!MY_API_URL"]
    }
  }
}

passThroughEnv

Cho phép env vars vào task runtime (strict mode) nhưng không ảnh hưởng hash:

./turbo.json

{
  "tasks": {
    "build": {
      "passThroughEnv": ["AWS_SECRET_KEY"]
    }
  }
}

outputs

Glob patterns chỉ định artifacts cần cache:

./turbo.json

{
  "tasks": {
    "build": {
      "outputs": ["dist/**", ".next/**"]
    }
  }
}

Bỏ qua hoặc [] → chỉ cache logs
Dùng negations: "!.next/cache/**"

inputs

Kiểm soát file nào thay đổi mới invalidate cache:

./turbo.json

{
  "tasks": {
    "test": {
      "inputs": ["src/**/*.ts", "test/**/*.ts"]
    }
  }
}

Ghi chú quan trọng: Dùng inputs sẽ opt-out khỏi default .gitignore behavior. Dùng $TURBO_DEFAULT$ để giữ default + mở rộng:

./turbo.json

{
  "tasks": {
    "check-types": {
      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
    }
  }
}

$TURBO_ROOT$ — glob relative đến repository root:

./turbo.json

{
  "tasks": {
    "check-types": {
      "inputs": ["$TURBO_ROOT$/tsconfig.json", "src/**/*.ts"]
    }
  }
}

Deferred Hashing — hash files sau khi dependencies chạy xong:

mode: "jit" — hash ngay trước khi task chạy
mode: "dependencyOutputs" — hash dựa trên outputs của dependency

./turbo.json

{
  "tasks": {
    "build": {
      "dependsOn": ["codegen"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "!src/generated/**",
        { "mode": "jit", "globs": ["src/generated/**"] }
      ]
    }
  }
}

cache

Tắt cache cho task (dev server):

./turbo.json

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

outputLogs

Kiểm soát log verbosity:

Option

Mô tả

full

Hiển thị tất cả logs (mặc định)

hash-only

Chỉ hiển thị hash

new-only

Chỉ log từ cache misses

errors-only

Chỉ log khi task fail

none

Ẩn tất cả

./turbo.json

{
  "tasks": {
    "build": {
      "outputLogs": "new-only"
    }
  }
}

persistent / interactive / interruptible

persistent: true — task chạy lâu dài (dev server). Các task khác không được dependsOn nó.
interactive: true — nhận input từ stdin, cần đi với persistent.
interruptible: true — cho phép turbo watch restart task persistent.

./turbo.json

{
  "tasks": {
    "test:watch": {
      "interactive": true,
      "persistent": true
    }
  }
}

with

Chạy task song song với task khác (hữu ích cho dev server):

./apps/web/turbo.json

{
  "tasks": {
    "dev": {
      "with": ["api#dev"],
      "persistent": true,
      "cache": false
    }
  }
}

description

Mô tả task (chỉ để documentation):

./turbo.json

{
  "tasks": {
    "build": {
      "description": "Compiles the application for production deployment"
    }
  }
}

3. Remote Caching

./turbo.json

{
  "remoteCache": {
    "enabled": true,
    "signature": true,
    "preflight": false,
    "timeout": 30,
    "uploadTimeout": 60,
    "apiUrl": "https://vercel.com",
    "loginUrl": "https://vercel.com",
    "teamId": "team_xxx",
    "teamSlug": "my-team"
  }
}

signature: true — sign artifacts với HMAC-SHA256. Cần set TURBO_REMOTE_CACHE_SIGNATURE_KEY.
preflight — OPTIONS request trước mỗi HTTP request.
timeout / uploadTimeout — timeout tính bằng seconds.

4. Future Flags

Các tính năng thử nghiệm sẽ trở thành default trong tương lai:

./turbo.json

{
  "futureFlags": {
    "errorsOnlyShowHash": true,
    "longerSignatureKey": true,
    "affectedUsingTaskInputs": true,
    "watchUsingTaskInputs": true,
    "pruneIncludesGlobalFiles": true,
    "filterUsingTasks": true,
    "globalConfiguration": true,
    "experimentalObservability": true
  }
}

errorsOnlyShowHash — khi dùng outputLogs: "errors-only", vẫn hiện hash cho task thành công.
longerSignatureKey — enforce key ≥ 32 bytes cho HMAC-SHA256.
affectedUsingTaskInputs — --affected hoạt động ở task-level (dựa trên inputs), không phải package-level.
pruneIncludesGlobalFiles — turbo prune copy cả globalDependencies files.
filterUsingTasks — --filter hoạt động ở task-level.
globalConfiguration — dồn global options vào key global:

./turbo.json

{
  "futureFlags": { "globalConfiguration": true },
  "global": {
    "inputs": ["tsconfig.json"],
    "env": ["NODE_ENV"],
    "passThroughEnv": ["AWS_SECRET_KEY"],
    "ui": "tui",
    "envMode": "strict",
    "concurrency": 4,
    "remoteCache": { ... }
  }
}

5. Boundaries

Enforce architectural rules giữa các package:

./turbo.json

{
  "boundaries": {
    "utils": {
      "dependencies": {
        "allow": ["ui"],
        "deny": ["unsafe"]
      },
      "dependents": {
        "allow": ["web"]
      }
    }
  }
}

Tags được khai báo trong Package Configurations:

./apps/web/turbo.json

{
  "tags": ["web"]
}

6. Experimental Observability

Gửi metrics đến OTLP collector (Datadog, Prometheus, etc.):

./turbo.json

{
  "futureFlags": { "experimentalObservability": true },
  "experimentalObservability": {
    "otel": {
      "enabled": true,
      "protocol": "grpc",
      "endpoint": "https://api.datadoghq.com/api/v2/otlp",
      "headers": {
        "DD-API-KEY": "xxx"
      },
      "timeoutMs": 10000,
      "intervalMs": 15000,
      "resource": {
        "service.name": "turborepo"
      },
      "metrics": {
        "runSummary": true,
        "taskDetails": false,
        "runAttributes": {
          "id": false,
          "scmRevision": false
        },
        "taskAttributes": {
          "id": false,
          "hashes": false
        }
      },
      "useRemoteCacheToken": false
    }
  }
}

Lưu ý: Endpoint bắt buộc dùng https://. Headers và token gắn với endpoint — nếu override endpoint từ nguồn ưu tiên cao hơn, credentials không được kế thừa.

7. Env Mode

Kiểm soát env vars available cho task:

./turbo.json

{
  "envMode": "strict"
}

"strict" (default) — chỉ cho phép env vars khai báo trong env và globalEnv.
"loose" — cho phép tất cả env vars của process.

8. Ví dụ Hoàn Chỉnh

./turbo.json

{
  "$schema": "https://turborepo.dev/schema.json",
  "globalDependencies": ["tsconfig.json"],
  "globalEnv": ["NODE_ENV", "CI"],
  "concurrency": 4,
  "cacheDir": ".turbo/cache",
  "cacheMaxAge": "7d",
  "cacheMaxSize": "10GB",
  "ui": "stream",
  "remoteCache": {
    "signature": true
  },
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "inputs": ["$TURBO_DEFAULT$", "!README.md"],
      "env": ["NEXT_PUBLIC_API_URL"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**/*.ts", "test/**/*.ts"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": [],
      "outputLogs": "errors-only"
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", "!**/*.test.ts"]
    }
  },
  "experimentalObservability": {
    "otel": {
      "enabled": true,
      "protocol": "grpc",
      "endpoint": "https://otel-collector:4317"
    }
  }
}

Tài liệu tham khảo

TrướcTurborepo Tiếp theoRunning Tasks

Cập nhật lần cuối 12 ngày trước