🆕 2025年11月最新版！
Nx 18、Turborepo 2.0、最新のCI/CDベストプラクティスを反映しました。

5分でわかる：モノレポ完全ガイド

複数プロジェクトを効率的に管理したい。そんなあなたのために、モノレポの全てを実践的に解説します。

なぜこのガイドが必要なのか

本記事で学べること

1. 基礎理解（第1-2章）：モノレポとは、メリット・デメリット
2. ツール選択（第3章）：7ツールの詳細比較
3. 実践構築（第4章）：環境構築ステップバイステップ
4. 最適化（第5-6章）：ビルド高速化、CI/CD効率化
5. トラブル解決（第7章）：よくあるエラー15選
6. 運用ノウハウ（第8章）：大規模チーム向けベストプラクティス

第1章：モノレポ完全解説

1.1 モノレポとは？

Monorepo（モノレポ）:
└─ 複数のプロジェクト/パッケージを
   単一リポジトリで管理する開発手法

マルチレポとの違い:

マルチレポ（従来型）:
project-A/
  └─ .git/
project-B/
  └─ .git/
project-C/
  └─ .git/

モノレポ:
monorepo/
├─ .git/
├─ packages/
│   ├── project-A/
│   ├── project-B/
│   └── project-C/

採用企業:
- Google（20億行以上のコード）
- Facebook（Meta）
- Microsoft
- Uber
- Twitter（X）

1.2 メリット・デメリット

✅ メリット:

1. コード共有の容易さ
└─ 共通ライブラリの再利用
   └─ 重複コード削減

2. 原子的な変更
└─ 複数プロジェクトを一括更新
   └─ バージョン不整合防止

3. 統一されたツールチェーン
└─ Lint、フォーマット、テスト
   └─ 開発体験の統一

4. リファクタリングの容易さ
└─ 全体的な影響を即座に確認
   └─ 技術的負債の削減

5. 依存関係の可視化
└─ プロジェクト間の関係性が明確
   └─ アーキテクチャ改善

❌ デメリット:

1. リポジトリサイズの増大
└─ クローン時間の増加
   解決策: Git sparse-checkout

2. ビルド時間の長期化
└─ 全体ビルドが遅い
   解決策: 増分ビルド、キャッシュ

3. アクセス権限管理
└─ 粒度の細かい制御が困難
   解決策: CODEOWNERS活用

4. 学習コスト
└─ ツール習得が必要
   解決策: ドキュメント整備

5. Git操作の複雑化
└─ マージ競合が増える
   解決策: ブランチ戦略整備

第2章：モノレポツール7選徹底比較

2.1 総合比較表

2.2 プロジェクトサイズ別推奨ツール

小規模（1-5プロジェクト）:
推奨: pnpm/Yarn/npm Workspaces
理由:
- 設定がシンプル
- 追加ツール不要
- 学習コスト最小

中規模（5-20プロジェクト）:
推奨: Turborepo + pnpm
理由:
- 高速なビルド
- 設定が少ない
- Next.js/Vercel統合

大規模（20-50プロジェクト）:
推奨: Nx
理由:
- 強力な依存解析
- 豊富なプラグイン
- 大規模最適化

超大規模（50+プロジェクト）:
推奨: Rush + pnpm
理由:
- 厳格なポリシー
- スケーラビリティ
- エンタープライズ向け

2.3 技術スタック別推奨

React/Next.js:
1位: Turborepo（Vercel製、統合良好）
2位: Nx（豊富なReactプラグイン）

Angular:
1位: Nx（Angular公式推奨）
2位: Rush

Node.js/TypeScript:
1位: pnpm Workspaces + Turborepo
2位: Lerna

ライブラリ公開:
1位: Lerna（npm publish最適化）
2位: Nx（公開機能あり）

フルスタック:
1位: Nx（フロント・バックエンド統合）
2位: Turborepo

第3章：環境構築ステップバイステップ

3.1 Turborepo + pnpm での構築（推奨）

# ステップ1: pnpmインストール
npm install -g pnpm

# ステップ2: プロジェクト作成
mkdir my-monorepo && cd my-monorepo
pnpm init

# ステップ3: Turborepo追加
pnpm add -Dw turbo

# ステップ4: ディレクトリ構造作成
mkdir -p apps/web apps/api packages/ui packages/utils

3.2 設定ファイル作成

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

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

// package.json（ルート）
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test"
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "@types/node": "^20.0.0",
    "typescript": "^5.3.0",
    "prettier": "^3.1.0",
    "eslint": "^8.56.0"
  }
}

3.3 Webアプリケーション追加

cd apps/web
pnpm init

// apps/web/package.json
{
  "name": "@my-monorepo/web",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "^14.0.4",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "@my-monorepo/ui": "workspace:*"
  }
}

3.4 共有UIライブラリ追加

cd packages/ui
pnpm init

// packages/ui/package.json
{
  "name": "@my-monorepo/ui",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "@types/react": "^18.2.0"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

第4章：ビルド最適化戦略

4.1 キャッシュ戦略

// turbo.json - 詳細キャッシュ設定
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"],
      "cache": true,
      "inputs": [
        "src/**/*.tsx",
        "src/**/*.ts",
        "package.json",
        "tsconfig.json"
      ]
    }
  }
}

4.2 並列実行の最適化

# 最大並列度指定
turbo run build --concurrency=4

# CPU数に応じて自動調整
turbo run build --concurrency=$(nproc)

# 並列実行（並列度無制限）
turbo run lint --parallel

4.3 増分ビルド

# 変更があったプロジェクトのみビルド
turbo run build --filter=[HEAD^1]

# 特定プロジェクトとその依存をビルド
turbo run build --filter=@my-monorepo/web...

# 特定プロジェクトに依存するものをビルド
turbo run build --filter=...@my-monorepo/ui

第5章：CI/CD最適化

5.1 GitHub Actions 最適化ワークフロー

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

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Turboの差分検出に必要
          
      - uses: pnpm/action-setup@v2
        with:
          version: 8
          
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
          
      # PNPM依存関係の高速インストール
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
        
      # Turboキャッシュの復元
      - name: Build
        run: pnpm turbo build --filter=[HEAD^1]
        
      - name: Test
        run: pnpm turbo test --filter=[HEAD^1]
        
      - name: Lint
        run: pnpm turbo lint --filter=[HEAD^1]

5.2 Docker最適化

# Dockerfile
FROM node:20-alpine AS base
RUN corepack enable
WORKDIR /app

FROM base AS builder
COPY . .
RUN pnpm install --frozen-lockfile
RUN pnpm turbo build --filter=@my-monorepo/web

FROM base AS runner
COPY --from=builder /app/apps/web/.next/standalone ./
COPY --from=builder /app/apps/web/.next/static ./apps/web/.next/static
COPY --from=builder /app/apps/web/public ./apps/web/public

EXPOSE 3000
CMD ["node", "apps/web/server.js"]

第6章：よくあるエラー15選と解決策

カテゴリ1：セットアップエラー（1-5）

エラー1：Workspaceパッケージが見つからない

エラーメッセージ：
Could not resolve "@my-monorepo/ui" from "apps/web/src/App.tsx"

原因：
- workspace設定が不正
- パッケージ名の不一致

解決策：

1. pnpm-workspace.yaml確認
```yaml
packages:
  - 'apps/*'
  - 'packages/*'

2. package.json の name確認

// packages/ui/package.json
{
  "name": "@my-monorepo/ui"  // これが正しいか確認
}

3. 依存関係の再インストール

pnpm install

#### エラー2-5のクイックリファレンス

| エラー | 原因 | 解決策 |
|--------|------|--------|
| **2. Turbo実行エラー** | turbo.json不正 | スキーマ検証、サンプルと比較 |
| **3. TypeScript解決エラー** | tsconfig paths | baseUrl、paths設定確認 |
| **4. Build順序エラー** | 依存関係不明確 | dependsOn設定 |
| **5. キャッシュ破損** | .turbo破損 | rm -rf .turbo |

### カテゴリ2：ビルド・実行エラー（6-10）

#### エラー6：循環依存

エラーメッセージ： Circular dependency detected

解決策：

1. 依存関係の可視化

pnpm why <package-name>

2. madgeで循環検出

npx madge --circular packages/

3. アーキテクチャ見直し

• 共通パッケージへの移動
• 依存方向の整理

#### エラー7-10のクイックリファレンス

| エラー | 原因 | 解決策 |
|--------|------|--------|
| **7. メモリ不足** | Node.jsヒープ | NODE_OPTIONS='--max-old-space-size=8192' |
| **8. ビルドタイムアウト** | 処理時間超過 | 並列度調整、キャッシュ活用 |
| **9. パスエラー** | 相対パス問題 | tsconfig paths、baseUrl |
| **10. バージョン競合** | 依存関係不一致 | pnpm dedupe、resolutions |

### カテゴリ3：CI/CDエラー（11-15）

#### エラー11：GitHub Actions キャッシュミス

原因： キャッシュキーの設定ミス

解決策：

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'pnpm'
    cache-dependency-path: 'pnpm-lock.yaml'

#### エラー12-15のクイックリファレンス

| エラー | 原因 | 解決策 |
|--------|------|--------|
| **12. 差分検出失敗** | git fetch不足 | fetch-depth: 0 |
| **13. 権限エラー** | GITHUB_TOKEN不足 | permissions設定 |
| **14. Turboリモートキャッシュ** | 認証失敗 | TURBO_TOKEN確認 |
| **15. デプロイ失敗** | ビルド成果物なし | outputs設定確認 |

## 第7章：大規模チーム運用

### 7.1 コード所有権管理

.github/CODEOWNERS

デフォルトオーナー

• @platform-team

アプリケーション

/apps/web/ @frontend-team /apps/api/ @backend-team /apps/mobile/ @mobile-team

共有パッケージ

/packages/ui/ @frontend-team @design-team /packages/api-client/ @backend-team @frontend-team /packages/utils/ @platform-team

インフラ・設定

/.github/ @devops-team /turbo.json @devops-team /pnpm-workspace.yaml @platform-team

### 7.2 ブランチ戦略

Git Flow for Monorepo:

main（本番） └── develop（開発） ├── feature/web/new-dashboard ├── feature/api/auth-improvement └── feature/ui/button-component

命名規則:

• feature//
• fix//
• chore//

scope:

• アプリ名: web, api, mobile
• パッケージ名: ui, utils
• 全体: monorepo

### 7.3 パフォーマンス監視

```typescript
// scripts/monitor-build-time.ts
import { execSync } from 'child_process';

const startTime = Date.now();

try {
  execSync('pnpm turbo build', { stdio: 'inherit' });
  
  const duration = (Date.now() - startTime) / 1000;
  console.log(`✅ Build completed in ${duration}s`);
  
  if (duration > 600) { // 10分超
    console.warn(`⚠️ Build time exceeded 10 minutes`);
    // Slack通知等
  }
} catch (error) {
  console.error('❌ Build failed');
  process.exit(1);
}

まとめ：モノレポで開発効率を最大化

モノレポは、複数プロジェクトの効率的管理を実現する強力なアーキテクチャです。

✅ モノレポを導入すべき理由

1. コード共有の効率化
   └─ 重複コード削減

2. 一括変更の容易さ
   └─ API変更を全体に反映

3. 統一された開発体験
   └─ ツールチェーン統一

4. ビルドの最適化
   └─ 増分ビルドで高速化

5. 依存関係の明確化
   └─ アーキテクチャ改善

6. CI/CDの効率化
   └─ 変更部分のみテスト

7. チーム協業の促進
   └─ コードレビュー効率化

今すぐモノレポを始めて、開発効率を3倍に。

※本記事の情報は2025年11月時点のものです。最新情報は各ツールの公式サイトでご確認ください。