Claude Code Turborepo：Claude Code 实战指南

Turborepoモノレポの构建を通过 Claude Code 加速

Turborepoは、Vercelが开发する高性能なモノレポ构建システムです。インクリメンタル构建とインテリジェント缓存により、大規模项目でも高速な构建を維持可以。Claude Codeを活用すれば、Turborepoの複雑な配置も高效地進められます。

项目の初期构建

> Turborepoでモノレポを新規创建して。
> 结构：
> - apps/web: Next.js App Router
> - apps/docs: Astro文档サイト
> - packages/ui: 共通UI库
> - packages/utils: ユーティリティ函数
> - packages/tsconfig: TypeScript配置

Claude Code 生成する turbo.json の配置例です。

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "out/**"],
      "env": ["NEXT_PUBLIC_API_URL"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    }
  }
}

流水线の依存関係设计

Turborepoの流水线では、任务間の依存関係を dependsOn で宣言します。

> 包間の依存を考慮して、build → test → deploy の
> 流水线を设计して。类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类类型チェックはbuildと并行で実行したい。

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "type-check": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "deploy": {
      "dependsOn": ["build", "test", "type-check"],
      "cache": false
    }
  }
}

build と type-check は互いに依存しないため、Turborepoが自動的に并行実行してくれます。

リモート缓存の配置

チーム开发ではリモート缓存が欠かせません。

> Vercel Remote Cacheを配置して。
> CI環境でも使えるようにしたい。

# Vercelアカウントとリンク
npx turbo login
npx turbo link

# CI環境用の設定（GitHub Actions）
# TURBO_TOKEN と TURBO_TEAM を secrets に設定

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm turbo build lint test --filter=...[HEAD^]

--filter=...[HEAD^] 使用ことで、更改のあった包だけを构建対象に可以。

フィルタリングで効率的な开发

> web应用だけをdevモードで起動して。
> 依存包のwatchも有效にして。

# 特定のアプリとその依存パッケージのみ実行
pnpm turbo dev --filter=web...

# 変更があったパッケージのみビルド
pnpm turbo build --filter=...[origin/main]

# 特定パッケージを除外
pnpm turbo build --filter=!./apps/docs

缓存の调试

构建缓存が効かない場合、让 Claude Code调试を依頼可以。

> turbo buildの缓存がヒットしない原因を調査して。
> turbo run build --dry=json の输出を确认して。

# キャッシュステータスの確認
pnpm turbo build --dry=json | jq '.tasks[] | {taskId, cache}'

# 詳細なログ出力
pnpm turbo build --verbosity=2

总结

借助 Claude Code，Turborepoの流水线设计や缓存戦略を快速优化可以。モノレポ管理の基本やCI/CD配置指南也建议一并参考。

Turborepoの詳しい配置はTurborepo官方文档。