Running Tasks

Hướng dẫn chạy tasks trong Turborepo — scripts trong package.json, global turbo, chạy đa tasks, automatic scoping, output logs và troubleshooting.

Sau khi cấu hình tasks trong turbo.json, Turborepo cung cấp nhiều cách để chạy chúng — từ package.json scripts, global CLI, cho đến filter linh hoạt.

1. Chạy qua scripts trong package.json

Cách đơn giản nhất: viết turbo commands vào root package.json:

{
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint"
  }
}

Sau đó chạy bằng package manager:

pnpm build
# hoặc
npm run build

Khuyến nghị: Dùng turbo run build thay vì turbo build trong package.json để tránh conflict với subcommands tương lai.

Cảnh báo: Chỉ viết turbo commands trong root package.json. Viết trong package sẽ gây recursive gọi turbo.

2. Chạy qua Global Turbo

Cài global (pnpm add turbo --global) → chạy trực tiếp từ terminal:

turbo build
turbo run build test lint
turbo build --filter=@repo/web
turbo build --dry
turbo build --output-logs=errors-only

Automatic Package Scoping

Khi đang trong thư mục của một package, turbo tự động scope:

cd apps/docs
turbo build  # chỉ chạy build cho docs + dependencies

Filter tường minh (--filter) sẽ override behavior này.

3. Chạy nhiều tasks cùng lúc

turbo run build test lint check-types

Turborepo tự động:

1. Parse dependency graph từ turbo.json

2. Xác định thứ tự tối ưu (DAG)

3. Parallelize tối đa dựa trên available cores

Thứ tự liệt kê không quan trọng. turbo test lint = turbo lint test. Dependency do dependsOn quyết định.

4. Output Logs

Kiểm soát log verbosity:

Lệnh	Kết quả
turbo build	Full logs (mặc định)
turbo build --output-logs=hash-only	Chỉ hash
turbo build --output-logs=new-only	Chỉ cache miss
turbo build --output-logs=errors-only	Chỉ lỗi
turbo build --output-logs=none	Không logs

Cấu hình permanent trong turbo.json:

{
  "tasks": {
    "lint": {
      "outputLogs": "errors-only"
    }
  }
}

5. Task Graph Visualization

turbo build --graph

Xuất đồ thị DAG của tasks dạng .dot (có thể render với Graphviz).

6. Dry Run

Xem task sẽ chạy thế nào mà không chạy thật:

turbo build --dry

turbo build --dry=json  # JSON format, dễ parse

Output gồm: packages, tasks, dependencies, hash của từng task. Dùng để debug cache miss.

7. Customizing Behavior

Override turbo.json từ CLI

# Override outputLogs
turbo lint --output-logs=errors-only

# Override concurrency
turbo build --concurrency=2

# Override cache
turbo build --no-cache
turbo build --force

# Override env mode
turbo build --env-mode=loose

Passthrough arguments

Truyền argument cho script bên dưới:

turbo build -- --my-flag value

Lưu ý: passthrough args ảnh hưởng global hash → miss cache.

8. Common Workflows

# Build tất cả
turbo run build

# Build + test + lint
turbo run build test lint

# Chỉ 1 package
turbo build --filter=@repo/web

# Package + dependencies của nó
turbo build --filter=@repo/web...

# Package + dependents của nó
turbo build --filter=...@repo/web

# Chỉ package thay đổi từ commit trước
turbo build --filter=[HEAD^1]

# Dev mode (nhiều app cùng lúc)
turbo run dev

# Type-check toàn bộ
turbo run typecheck

9. Lưu ý

• Task không có trong turbo.json nhưng có trong package.json → chạy được nhưng không có caching/parallel

• Dùng turbo run <task> thay vì turbo <task> trong script scripts để an toàn

• --dry và --graph là công cụ debug mạnh khi cache behavior không như mong đợi

Tài liệu tham khảo

• Running Tasks (official)

• turbo run reference

• Configuring Tasks