Turborepo Caching

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	長時間実行タスク（dev サーバー）

テンプレート

テンプレート 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": ["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": ["src/**", "tests/**", "jest.config.js"]
    }
  }
}

テンプレート 3: Vercel によるリモートキャッシング

# Vercel にログイン
npx turbo login

# Vercel プロジェクトにリンク
npx turbo link

# リモートキャッシュで実行
turbo build --remote-only

# CI 環境変数
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: セルフホストリモートキャッシュ

// カスタムリモートキャッシュサーバー（Express）
import express from "express";
import { createReadStream, createWriteStream } from "fs";
import { mkdir } from "fs/promises";
import { join } from "path";

const app = express();
const CACHE_DIR = "./cache";

// アーティファクトの取得
app.get("/v8/artifacts/:hash", async (req, res) => {
  const { hash } = req.params;
  const team = req.query.teamId || "default";
  const filePath = join(CACHE_DIR, team, hash);

  try {
    const stream = createReadStream(filePath);
    stream.pipe(res);
  } catch {
    res.status(404).send("Not found");
  }
});

// アーティファクトの保存
app.put("/v8/artifacts/:hash", async (req, res) => {
  const { hash } = req.params;
  const team = req.query.teamId || "default";
  const dir = join(CACHE_DIR, team);
  const filePath = join(dir, hash);

  await mkdir(dir, { recursive: true });

  const stream = createWriteStream(filePath);
  req.pipe(stream);

  stream.on("finish", () => {
    res.json({
      urls: [`${req.protocol}://${req.get("host")}/v8/artifacts/${hash}`],
    });
  });
});

// アーティファクトの存在確認
app.head("/v8/artifacts/:hash", async (req, res) => {
  const { hash } = req.params;
  const team = req.query.teamId || "default";
  const filePath = join(CACHE_DIR, team, hash);

  try {
    await fs.access(filePath);
    res.status(200).end();
  } catch {
    res.status(404).end();
  }
});

app.listen(3000);

// セルフホストキャッシュ用の turbo.json
{
  "remoteCache": {
    "signature": false
  }
}

# セルフホストキャッシュの使用
turbo build --api="http://localhost:3000" --token="my-token" --team="my-team"

テンプレート 5: フィルタリングとスコーピング

# 特定のパッケージをビルド
turbo build --filter=@myorg/web

# パッケージと依存関係をビルド
turbo build --filter=@myorg/web...

# パッケージと依存するパッケージをビルド
turbo build --filter=...@myorg/ui

# main 以降で変更されたパッケージをビルド
turbo build --filter='...[origin/main]'

# ディレクトリ内のパッケージをビルド
turbo build --filter='./apps/*'

# フィルタを結合
turbo build --filter=@myorg/web --filter=@myorg/docs

# パッケージを除外
turbo build --filter='!@myorg/docs'

# 変更の依存関係を含める
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": ["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": "npm@10.0.0"
}

キャッシュのデバッグ

# ドライランで実行内容を確認
turbo build --dry-run

# ハッシュを含む詳細出力
turbo build --verbosity=2

# タスクグラフを表示
turbo build --graph

# キャッシュを強制的に無効化
turbo build --force

# キャッシュ状態を表示
turbo build --summarize

# 特定のタスクをデバッグ
TURBO_LOG_VERBOSITY=debug turbo build --filter=@myorg/web

ベストプラクティス

すべきこと

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

してはいけないこと

• dev サーバーをキャッシュしない - persistent: true を使用
• シークレットを env に含めない - 実行時環境変数を使用
• dependsOn を無視しない - レース条件を引き起こす
• 過度なフィルタリング - 依存関係を見落とすことがある