turborepo-caching

Turborepo のキャッシュ

Turborepo のビルドを最適化するための実践的なパターンです。

このスキルを使用しない場合

• タスクが Turborepo のキャッシュに関係しない場合
• この範囲外の別の分野やツールが必要な場合

手順

• 目標、制約、必要な入力を確認します。
• 関連するベストプラクティスを適用し、結果を検証します。
• 実行可能な手順と検証方法を提示します。

このスキルを使用する場合

• 新しい Turborepo プロジェクトを設定するとき
• ビルドパイプラインを構成するとき
• リモートキャッシュを導入するとき
• CI/CD のパフォーマンスを最適化するとき
• 他のモノレポツールから移行するとき
• キャッシュミスをデバッグするとき

基本概念

1. Turborepo のアーキテクチャ

Workspace Root/
├── apps/
│   ├── web/
│   │   └── package.json
│   └── docs/
│       └── package.json
├── packages/
│   ├── ui/
│   │   └── package.json
│   └── config/
│       └── package.json
├── turbo.json
└── package.json

2. パイプラインの概念

概念	説明
dependsOn	先に完了する必要があるタスク
cache	出力をキャッシュするかどうか
outputs	キャッシュするファイル
inputs	キャッシュキーに影響するファイル
persistent	長時間実行されるタスク（開発サーバー）

バージョンとキャッシュの正確性

以下の JSON は Turbo 1.x 形式（^1.10.0 という説明用の依存関係に対応する pipeline）です。Turbo 2 では tasks を使用します。インストール済みのバージョンに対応するスキーマと移行ドキュメントを参照してください。inputs を明示的に指定するとデフォルト設定が置き換わります。テストやビルドの古い成功結果が使われないように、$TURBO_DEFAULT$ または実際に使用されるすべてのソース、設定、依存関係の入力を含めてください。シークレットを含む出力は決してキャッシュせず、必要な外部状態が紐付けられていない場合は、キャッシュ済みの成功結果を再利用しないでください。

テンプレート

テンプレート 1：turbo.json の設定

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [
    ".env",
    ".env.local"
  ],
  "globalEnv": [
    "NODE_ENV",
    "VERCEL_URL"
  ],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [
        "dist/**",
        ".next/**",
        "!.next/cache/**"
      ],
      "env": [
        "API_URL",
        "NEXT_PUBLIC_*"
      ]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "src/**/*.tsx",
        "src/**/*.ts",
        "test/**/*.ts"
      ]
    },
    "lint": {
      "outputs": [],
      "cache": true
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

テンプレート 2：パッケージ固有のパイプライン

// apps/web/turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "extends": ["//"],
  "pipeline": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**"],
      "env": [
        "NEXT_PUBLIC_API_URL",
        "NEXT_PUBLIC_ANALYTICS_ID"
      ]
    },
    "test": {
      "outputs": ["coverage/**"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "src/**",
        "tests/**",
        "jest.config.js"
      ]
    }
  }
}

テンプレート 3：Vercel を使用したリモートキャッシュ

# Login to Vercel
npx turbo login

# Link to Vercel project
npx turbo link

# Run with remote cache
turbo build --remote-only

# CI environment variables
TURBO_TOKEN=your-token
TURBO_TEAM=your-team

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npx turbo build --filter='...[origin/main]'

      - name: Test
        run: npx turbo test --filter='...[origin/main]'

テンプレート 4：セルフホスト型リモートキャッシュ

インストール済みの Turbo リモートキャッシュプロトコルを実装した、レビュー済みのサーバーを使用してください。認証、サーバー側でのテナント認可、アーティファクトサイズの上限設定、安全なハッシュとパスの検証、アトミックな書き込み、ストリームのエラー処理、保持期間を必須にしてください。信頼できない teamId や hash の値をファイルシステムのパスに結合して、本番用キャッシュを構築しないでください。サポートされているアーティファクト署名を有効にし、エンドツーエンドで検証してください。共有キャッシュから実行可能なビルド出力が提供される可能性があります。トークンをコマンド引数やログに含めず、信頼できない PR には書き込みアクセスを許可しないでください。

テンプレート 5：フィルタリングとスコープ設定

# Build specific package
turbo build --filter=@myorg/web

# Build package and its dependencies
turbo build --filter=@myorg/web...

# Build package and its dependents
turbo build --filter=...@myorg/ui

# Build changed packages since main
turbo build --filter='...[origin/main]'

# Build packages in directory
turbo build --filter='./apps/*'

# Combine filters
turbo build --filter=@myorg/web --filter=@myorg/docs

# Exclude package
turbo build --filter='!@myorg/docs'

# Include dependencies of changed
turbo build --filter='...[HEAD^1]...'

テンプレート 6：高度なパイプライン設定

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "!**/*.md",
        "!**/*.test.*"
      ]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "src/**",
        "tests/**",
        "*.config.*"
      ],
      "env": ["CI", "NODE_ENV"]
    },
    "test:e2e": {
      "dependsOn": ["build"],
      "outputs": [],
      "cache": false
    },
    "deploy": {
      "dependsOn": ["build", "test", "lint"],
      "outputs": [],
      "cache": false
    },
    "db:generate": {
      "cache": false
    },
    "db:push": {
      "cache": false,
      "dependsOn": ["db:generate"]
    },
    "@myorg/web#build": {
      "dependsOn": ["^build", "@myorg/db#db:generate"],
      "outputs": [".next/**"],
      "env": ["NEXT_PUBLIC_*"]
    }
  }
}

テンプレート 7：ルートの package.json の設定

{
  "name": "my-turborepo",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "test": "turbo test",
    "clean": "turbo clean && rm -rf node_modules",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "changeset": "changeset",
    "version-packages": "changeset version",
    "release": "turbo build --filter=./packages/* && changeset publish"
  },
  "devDependencies": {
    "turbo": "^1.10.0",
    "prettier": "^3.0.0",
    "@changesets/cli": "^2.26.0"
  },
  "packageManager": "[email protected]"
}

キャッシュのデバッグ

# Dry run to see what would run
turbo build --dry-run

# Verbose output with hashes
turbo build --verbosity=2

# Show task graph
turbo build --graph

# Force no cache
turbo build --force

# Show cache status
turbo build --summarize

# Debug specific task
TURBO_LOG_VERBOSITY=debug turbo build --filter=@myorg/web

ベストプラクティス

推奨事項

• 入力を明示的に定義する - キャッシュ無効化を避けます
• ワークスペースプロトコルを使用する - "@myorg/ui": "workspace:*"
• リモートキャッシュを有効にする - CI とローカル環境で共有します
• CI でフィルタリングする - 影響を受けるパッケージのみをビルドします
• ビルド出力をキャッシュする - ソースファイルはキャッシュしません

禁止事項

• 開発サーバーをキャッシュしない - persistent: true を使用します
• 環境変数にシークレットを含めない - ランタイム環境変数を使用します
• dependsOn を無視しない - 競合状態の原因になります
• 過度にフィルタリングしない - 依存関係を見落とす可能性があります

リソース

• Turborepo のドキュメント
• キャッシュガイド
• リモートキャッシュ

制限事項

• タスクが上記の説明された範囲に明確に該当する場合に限り、このスキルを使用してください。
• 出力を、環境に応じた検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、成功基準が不足している場合は、作業を中断して確認してください。