モノレポ戦略ガイド2025：Nx vs Turborepo vs Lerna — 大規模コードベース管理の完全ガイド

プロジェクト開始？
├── 小規模（パッケージ10個未満）
│   ├── 素早く始めたい → Turborepo
│   └── コード生成が必要 → Nx
├── 中規模（パッケージ10-50個）
│   ├── Vercel/Next.jsエコシステム → Turborepo
│   ├── 豊富なプラグインが必要 → Nx
│   └── 既にLernaを使用中 → Lerna v7
└── 大規模（パッケージ50個以上）
    ├── 分散実行が必要 → Nx
    └── Microsoftスタイル → Rush

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── .npmrc
├── apps/
│   ├── web/
│   │   └── package.json
│   └── api/
│       └── package.json
├── packages/
│   ├── ui/
│   │   └── package.json
│   ├── utils/
│   │   └── package.json
│   └── config/
│       └── package.json
└── tooling/
    ├── eslint/
    │   └── package.json
    └── typescript/
        └── package.json

packages:
  - "apps/*"
  - "packages/*"
  - "tooling/*"

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "clean": "turbo run clean"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  },
  "packageManager": "pnpm@9.0.0"
}

{
  "name": "@myorg/web",
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

# ホイスティング設定
shamefully-hoist=false
strict-peer-dependencies=false

# ワークスペース設定
link-workspace-packages=true
prefer-workspace-packages=true

# 新しいNxワークスペース作成
npx create-nx-workspace@latest my-monorepo --preset=ts

# 既存のモノレポにNxを追加
npx nx@latest init

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/tsconfig.spec.json"
    ],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  }
}

# プロジェクト依存関係グラフを可視化
npx nx graph

# 特定プロジェクトにフォーカス
npx nx graph --focus=my-app

# 影響を受けるプロジェクトを確認
npx nx affected:graph

プロジェクトグラフの例:

    web-app ───▶ ui-lib ───▶ utils
       │            │
       ▼            ▼
    api-app ───▶ shared-types

# 変更に影響を受けるプロジェクトのみビルド
npx nx affected -t build

# 影響を受けるプロジェクトのみテスト
npx nx affected -t test

# ベースブランチを指定
npx nx affected -t build --base=main --head=HEAD

# Reactコンポーネント生成
npx nx generate @nx/react:component Button --project=ui

# ライブラリ生成
npx nx generate @nx/js:library shared-utils

# カスタムGenerator作成
npx nx generate @nx/plugin:generator my-generator --project=tools

# Nx Cloudに接続
npx nx connect

# NxでのCI設定
name: CI
on: [push]
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
      - run: pnpm install --frozen-lockfile
      - uses: nrwl/nx-set-shas@v4
      - run: npx nx affected -t lint test build

# 新しいTurborepoプロジェクト作成
npx create-turbo@latest

# 既存のモノレポにTurborepoを追加
pnpm add -D turbo -w

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["DATABASE_URL"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["$TURBO_DEFAULT$"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "cache": true
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

turbo run build実行時:

1. 依存関係グラフ分析
   utils（依存なし）→ ui（utilsに依存）→ web（ui、utilsに依存）

2. 並列実行
   [utils: build] ──完了──▶ [ui: build] ──完了──▶ [web: build]
                            [api: build] ──────────┘
                              （utilsにのみ依存）

3. キャッシュ
   - 入力ファイルのハッシュを計算
   - 前回のビルドとハッシュが同じならキャッシュから復元
   - ビルド時間: 5分 → 0.1秒（キャッシュヒット）

# ローカルキャッシュの場所
ls node_modules/.cache/turbo/

# キャッシュ状態確認
turbo run build --dry-run

# キャッシュ無効化
turbo run build --force

# リモートキャッシュ有効化
npx turbo login
npx turbo link

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

# 変更されたパッケージのみビルド
turbo run build --filter=...[HEAD^1]

# 特定パッケージとその依存関係のみビルド
turbo run build --filter=@myorg/web...

# 特定ディレクトリのパッケージ
turbo run build --filter=./apps/*

# Vercel Remote Cache（公式）
npx turbo login
npx turbo link

TURBO_TOKEN=your-token
TURBO_TEAM=your-team
TURBO_API=https://your-cache-server.com

packages/
├── ui/              # UIコンポーネント（Button, Modal, Form）
├── utils/           # ユーティリティ（日付、文字列、バリデーション）
├── types/           # 共有TypeScriptタイプ
├── config/          # 共有設定（ESLint, TypeScript, Prettier）
├── hooks/           # 共有React hooks
├── api-client/      # APIクライアント（型安全なfetch）
└── constants/       # 定数（エラーコード、ルートパス）

{
  "name": "@myorg/ui",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts",
    "./*": "./src/*.ts"
  }
}

{
  "compilerOptions": {
    "paths": {
      "@myorg/ui": ["../../packages/ui/src"],
      "@myorg/ui/*": ["../../packages/ui/src/*"]
    }
  }
}

{
  "name": "@myorg/utils",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts"
  }
}

# インストール
pnpm add -D @changesets/cli -w

# 初期化
pnpm changeset init

# 1. 変更説明を追加
pnpm changeset
# ? どのパッケージが変更されましたか？ → @myorg/ui, @myorg/utils
# ? 変更タイプは？ → minor（新機能）
# ? 説明は？ → Added new Button variant

# 2. .changeset/ディレクトリにファイル生成
cat .changeset/brave-dogs-run.md
# ---
# "@myorg/ui": minor
# "@myorg/utils": patch
# ---
#
# Added new Button variant

# 3. バージョン更新（CIで実行）
pnpm changeset version

# 4. 公開
pnpm changeset publish

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [["@myorg/ui", "@myorg/hooks"]],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@myorg/web", "@myorg/api"]
}

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v2
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - run: pnpm install --frozen-lockfile

      # Turborepo: 変更されたパッケージのみビルド
      - run: turbo run build test lint --filter=...[origin/main]

キャッシュなし:
  lint（2分） + test（5分） + build（8分） = 15分

リモートキャッシュヒット:
  lint（0.1秒） + test（0.2秒） + build（0.3秒） = 0.6秒

実際に変更されたパッケージのみ:
  lint（20秒） + test（1分） + build（2分） = 3分20秒

# マトリックス戦略で並列実行
jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.filter.outputs.packages }}
    steps:
      - uses: actions/checkout@v4
      - id: filter
        run: echo "packages=$(turbo run build --filter=...[origin/main] --dry-run=json | jq -c '.packages')" >> $GITHUB_OUTPUT

  build:
    needs: detect
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: ${{ fromJson(needs.detect.outputs.packages) }}
    steps:
      - uses: actions/checkout@v4
      - run: turbo run build --filter=${{ matrix.package }}

# モノレポでのDockerビルド
FROM node:20-slim AS base
RUN corepack enable

FROM base AS pruned
WORKDIR /app
COPY . .
# turbo prune: 特定のアプリとその依存関係のみ抽出
RUN npx turbo prune @myorg/api --docker

FROM base AS installer
WORKDIR /app
# 依存関係のみ先にインストール（キャッシュレイヤー）
COPY --from=pruned /app/out/json/ .
COPY --from=pruned /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
RUN pnpm install --frozen-lockfile

# ソースをコピーしてビルド
COPY --from=pruned /app/out/full/ .
RUN pnpm turbo run build --filter=@myorg/api

FROM base AS runner
WORKDIR /app
COPY --from=installer /app/apps/api/dist ./dist
COPY --from=installer /app/node_modules ./node_modules
CMD ["node", "dist/main.js"]

# .github/CODEOWNERS

# グローバルデフォルトオーナー
* @org/platform-team

# アプリ別オーナー
/apps/web/          @org/frontend-team
/apps/api/          @org/backend-team
/apps/mobile/       @org/mobile-team

# パッケージ別オーナー
/packages/ui/       @org/design-system-team
/packages/utils/    @org/platform-team
/packages/auth/     @org/security-team

# 設定ファイル
/tooling/           @org/dx-team
/.github/           @org/dx-team
/turbo.json         @org/dx-team

// .eslintrc.json
{
  "rules": {
    "@nx/enforce-module-boundaries": [
      "error",
      {
        "depConstraints": [
          {
            "sourceTag": "scope:web",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:web"]
          },
          {
            "sourceTag": "scope:api",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:api"]
          },
          {
            "sourceTag": "type:app",
            "onlyDependOnLibsWithTags": ["type:lib", "type:util"]
          }
        ]
      }
    ]
  }
}

# 新しいモノレポリポジトリ作成
mkdir my-monorepo && cd my-monorepo
git init
pnpm init

# 既存リポジトリをサブディレクトリに移動（ヒストリー保存）
git remote add -f web-repo https://github.com/org/web-app.git
git merge web-repo/main --allow-unrelated-histories

# git-filter-repoでディレクトリ構造を変更
git filter-repo --to-subdirectory-filter apps/web

# pnpmワークスペース設定
cat > pnpm-workspace.yaml << 'EOF'
packages:
  - "apps/*"
  - "packages/*"
EOF

# 重複コードを共有パッケージに抽出
mkdir -p packages/shared-utils/src
# 共通ユーティリティを移動してパッケージを設定

# TurborepoまたはNxを設定
pnpm add -D turbo -w
# turbo.jsonを設定（6.2節参照）

# Before: 全パッケージビルド（15分）
pnpm -r run build

# After: 変更されたパッケージのみ（2分）
turbo run build --filter=...[origin/main]

# syncpackで依存性バージョン確認
npx syncpack list-mismatches
npx syncpack fix-mismatches

# Shallow clone
git clone --depth 1 https://github.com/org/monorepo.git

# Partial clone（blobなし）
git clone --filter=blob:none https://github.com/org/monorepo.git

# Sparse checkout（特定ディレクトリのみ）
git clone --sparse https://github.com/org/monorepo.git
cd monorepo
git sparse-checkout set apps/web packages/ui

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}