はじめに
「複数のアプリやパッケージが増えてきて、リポジトリ管理が煩雑になってきた」
「TurborepoとNxのどちらを使えばいいか判断できない」
「モノレポに移行したいが、既存プロジェクトの移行方法がわからない」
アプリケーションが成長するにつれ、複数のパッケージやアプリを一つのリポジトリで管理するモノレポ構成が有効になります。Claude Codeを使えば、モノレポの設計・移行・最適化を効率的に進められます。
目次
- モノレポとは何か・いつ採用するか
- Turborepo vs Nx：選択基準
- Turborepoを使ったモノレポ構築
- Nxを使ったモノレポ構築
- 既存プロジェクトのモノレポ移行
- パッケージ間の依存関係管理
- CI/CDの最適化
- まとめ
1. モノレポとは何か・いつ採用するか
モノレポ採用の判断基準
> 現在のプロジェクト構成を見て、
モノレポに移行すべきかどうかアドバイスしてください。
現在の構成：
- フロントエンド（Next.js）：別リポジトリ
- バックエンドAPI（Node.js）：別リポジトリ
- 共通の型定義：コピペで管理
- UIコンポーネントライブラリ：別リポジトリ
移行のメリット・デメリットと、
移行する場合のスコープを提案してください。モノレポのメリット・デメリット
| メリット | デメリット |
|---|---|
| コードの共有が容易 | リポジトリが大きくなる |
| 型定義の一元管理 | CI/CDの設定が複雑になる |
| 一括でリファクタリング可能 | チームの習熟コストがある |
| 依存関係の整合性が取りやすい | ビルド時間が増加する可能性 |
2. Turborepo vs Nx：選択基準
どちらを選ぶかの判断
> TurborepoとNxを比較して、
私たちのプロジェクトに最適な選択を提案してください。
プロジェクト情報：
- チーム規模：5名
- アプリ数：3つ（Next.js × 2・Electron × 1）
- 共有パッケージ数：現在0（移行後に増える見込み）
- 主な言語：TypeScript
選択基準のポイントをわかりやすく説明してください。簡易比較表：
| 観点 | Turborepo | Nx |
|---|---|---|
| 学習コスト | 低い | やや高い |
| 設定の柔軟性 | シンプル | 高機能 |
| コードジェネレーター | なし | あり（nx generate） |
| プラグインエコシステム | 小さい | 大きい |
| 向いているケース | 中小規模・シンプル構成 | 大規模・複雑な依存関係 |
3. Turborepoを使ったモノレポ構築
Turborepoプロジェクトの初期設定
> Turborepoを使ったモノレポを構築してください。
構成：
apps/
├── web（Next.js 14）
├── api（Express + TypeScript）
└── docs（Docusaurus）
packages/
├── ui（共通UIコンポーネント）
├── types（共通型定義）
├── config（ESLint・TypeScript設定）
└── utils（共通ユーティリティ）
設定内容：
- turbo.jsonのパイプライン設定
- 各パッケージのpackage.json
- TypeScriptのproject references設定
- ESLint・Prettierの共通設定ビルドパイプラインの最適化
> turbo.jsonのパイプラインを最適化してください。
現在の問題：
- 変更がないパッケージも毎回ビルドされている
- テストが順次実行されて時間がかかっている
設定したい内容：
- キャッシュの適切な設定（inputsの指定）
- 並列実行できるタスクの特定
- 依存関係に基づいた正しいビルド順序
- Vercel Remote Cacheの設定4. Nxを使ったモノレポ構築
Nxプロジェクトの初期設定
> Nxを使ったモノレポを構築してください。
構成：
- Next.jsアプリ（admin・customer）
- NestJSバックエンド
- 共有UIライブラリ（Storybook付き）
- 共有データアクセス層
設定内容：
- nx.jsonの設定
- プロジェクト間の依存グラフの設定
- nx generateによるコード生成のカスタマイズ
- Nxクラウドの設定（キャッシュ共有）affected コマンドの活用
> NxのaffectedコマンドをCI/CDに組み込んでください。
目標：変更された部分とその依存先のみビルド・テストを実行する
設定内容：
- nx affected --target=buildの設定
- nx affected --target=testの設定
- ベースブランチの設定（main）
- PRでの影響範囲の可視化5. 既存プロジェクトのモノレポ移行
段階的な移行計画
> 3つの別々のリポジトリをTurborepoのモノレポに移行する
段階的な計画を立ててください。
移行対象：
- frontend-repo（Next.js）
- backend-repo（Express）
- shared-types-repo（TypeScript型定義）
制約：
- 移行中も各リポジトリの開発を継続できること
- 本番環境のデプロイフローを壊さないこと
- Gitの履歴を保持すること（git subtreeを使用）
各フェーズの詳細な手順を教えてください。6. パッケージ間の依存関係管理
循環依存の検出と解消
> このモノレポで循環依存が発生しています。
影響範囲を特定して解消してください。
nx graph を実行して依存グラフを確認してから、
循環を解消するためのリファクタリング計画を立ててください。内部パッケージのバージョン管理
> モノレポ内のパッケージのバージョン管理方法を設定してください。
方針：
- Fixed Versioning（全パッケージを同一バージョンで管理）か
Independent Versioning（各パッケージ独立）かを推奨してください
- Changesetを使ったバージョン管理の設定
- CHANGELOGの自動生成
- npmへの自動公開（public packageの場合）7. CI/CDの最適化
GitHub Actionsのモノレポ対応
> このモノレポ用のGitHub Actionsワークフローを設計してください。
要件：
- 変更されたパッケージとその依存先のみビルド・テスト
- アプリごとに独立したデプロイジョブ
- キャッシュを最大限活用して実行時間を短縮
- PRごとに影響範囲をコメントで可視化
TurborepoまたはNxのaffectedコマンドを活用してください。8. まとめ
Claude CodeでのMonorepo管理の効率化ポイント：
- 複数リポジトリからの移行計画を段階的に立案できる
- Turborepo・Nxのビルドパイプライン設定を自動最適化
- 循環依存の検出と解消を自律的に実施
- CI/CDの最適化（affected build）を自動設定
ツール選択の目安：
- シンプルに始めたい → Turborepo
- 大規模・コードジェネレーターが必要 → Nx
- どちらでも → まずTurborepoで始めて必要になったらNxに移行
次回の第36回：Webhookを実装する方法では、イベント駆動アーキテクチャをClaude Codeで自動構築する手順を解説します。
よくある質問（FAQ）
Q. pnpm・yarn workspaces・npm workspacesの違いは？
A. モノレポではpnpmが最も効率的（ディスク使用量・インストール速度）なためClaude Codeでもpnpmを推奨します。「pnpm workspacesを使ったモノレポを構築してください」と指定することで対応できます。
この記事はClaude Code入門シリーズ（第4部）の第35回です。← 第34回：GraphQL API開発 ｜ 第36回：Webhook実装 →
ご質問はお問い合わせページからお気軽にどうぞ。
