Filtering Workspaces

Hướng dẫn sử dụng --filter trong Turborepo — lọc package theo tên, thư mục, source control changes, kết hợp filters và advanced patterns.

--filter cho phép chạy tasks trên một subset của monorepo, thay vì toàn bộ. Kết hợp với caching, đây là công cụ mạnh để tối ưu CI và dev workflow.

1. Filter theo package name

turbo build --filter=@repo/web
turbo build --filter=@repo/ui

2. Filter theo thư mục

# Tất cả package trong apps/
turbo build --filter="./apps/*"

# Tất cả package trong packages/utilities/
turbo lint --filter="./packages/utilities/*"

3. Bao gồm dependencies (suffix ...)

Chạy task cho package và dependencies của nó:

turbo dev --filter=web...

Thứ tự: dependencies → web (theo đúng task graph).

4. Bao gồm dependents (prefix ...)

Chạy task cho package và các package phụ thuộc vào nó:

turbo build --filter=...ui

Hữu ích khi sửa ui — kiểm tra xem web, docs có bị ảnh hưởng không.

5. Filter theo source control changes

Bắt buộc wrap trong []:

# So với commit trước
turbo build --filter=[HEAD^1]

# So với main branch
turbo build --filter=[main...my-feature]

# So với specific commits
turbo build --filter=[a1b2c3d...e4f5g6h]

# Branch name
turbo build --filter=[main...feature/auth]

Turborepo tính diff files giữa 2 mốc, map vào packages, chỉ chạy task cho packages có thay đổi.

6. Direct task filtering (từ v2.2.4)

Không cần --filter, filter trực tiếp trong lệnh:

# Chạy build cho web
turbo run web#build

# Chạy build cho web + lint cho docs
turbo run web#build docs#lint

7. Kết hợp nhiều filters

Multiple filters = union (OR):

turbo build --filter=...ui --filter={./packages/*} --filter=[HEAD^1]

Task graph sẽ include packages thỏa mãn bất kỳ filter nào.

8. Advanced Patterns

Exclude packages

# Tất cả trừ @repo/docs
turbo build --filter=!@repo/docs

# Tất cả trong apps/ trừ web
turbo build --filter="./apps/*" --filter=!@repo/web

Filter by git changes + dependencies

# Package thay đổi so với main + dependents của chúng
turbo build --filter=[main...HEAD]... --filter=...[main...HEAD]

9. Use Cases

Mục đích	Lệnh
Build toàn bộ	turbo build
Chỉ 1 app	turbo build --filter=@repo/web
App + dependencies	turbo build --filter=@repo/web...
Library + tất cả app dùng nó	turbo build --filter=...@repo/ui
Chỉ package thay đổi từ commit trước	turbo build --filter=[HEAD^1]
Chỉ package thay đổi trong PR	turbo build --filter=[main...HEAD]
CI: affected packages + dependents	turbo build --filter=[main...HEAD]...

10. CI Workflow Example

name: CI
on: [pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
      - run: pnpm install
      - run: pnpm turbo build test lint
        --filter=[main...HEAD]...
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

fetch-depth: 0 cần thiết để git diff hoạt động chính xác.

11. Lưu ý

• Filter vs Cache: filter giới hạn entrypoints vào task graph. Nếu package A phụ thuộc B, filter A → B vẫn chạy (nếu dependsOn yêu cầu)

• Dùng caching + Remote Cache để package không thay đổi vẫn hit cache dù không bị filter

• Filter source control yêu cầu full git history trong CI

Tài liệu tham khảo

• Running Tasks (official)

• --filter API Reference