monorepo-management

モノレポの管理

複数のパッケージやアプリケーションにわたるコード共有、一貫性のあるツール利用、アトミックな変更を実現する、効率的でスケーラブルなモノレポを構築します。

このスキルを使う場面

• 新しいモノレポプロジェクトのセットアップ
• マルチレポからモノレポへの移行
• ビルドとテストのパフォーマンスの最適化
• 共有依存関係の管理
• コード共有戦略の実装
• モノレポ向け CI/CD のセットアップ
• パッケージのバージョン管理と公開
• モノレポ固有の問題のデバッグ

主な概念

1. モノレポを使う理由

メリット：

• コードと依存関係を共有できる
• プロジェクト間でアトミックなコミットができる
• ツールと標準に一貫性を持たせられる
• リファクタリングが容易になる
• 依存関係の管理が簡素化される
• コードをより把握しやすくなる

課題：

• 大規模環境でのビルドパフォーマンス
• CI/CD の複雑さ
• アクセス制御
• 大規模な Git リポジトリ

2. モノレポツール

パッケージマネージャー：

• pnpm workspaces（推奨）
• npm workspaces
• Yarn workspaces

ビルドシステム：

• Turborepo（ほとんどの場合に推奨）
• Nx（機能が豊富で複雑）
• Lerna（旧式で、メンテナンスモード）

Turborepo のセットアップ

初期セットアップ

# Create new monorepo
npx create-turbo@latest my-monorepo
cd my-monorepo

# Structure:
# apps/
#   web/          - Next.js app
#   docs/         - Documentation site
# packages/
#   ui/           - Shared UI components
#   config/       - Shared configurations
#   tsconfig/     - Shared TypeScript configs
# turbo.json      - Turborepo configuration
# package.json    - Root package.json

設定

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

// package.json (root)
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "clean": "turbo run clean && rm -rf node_modules"
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0"
  },
  "packageManager": "[email protected]"
}

pnpm がワークスペースパッケージを読み込むのは pnpm-workspace.yaml のみです。そのため、パッケージはこのファイルに宣言してください（references/details.md を参照）。Turborepo 2 では pipeline が tasks に変更され、引き続き pipeline を使う turbo.json は拒否されます。1.x の設定をアップグレードするには、npx @turbo/codemod migrate を実行してください。

パッケージ構成

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./button": {
      "import": "./dist/button.js",
      "types": "./dist/button.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
    "lint": "eslint src/",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "@repo/tsconfig": "workspace:*",
    "tsup": "^7.0.0",
    "typescript": "^5.0.0"
  },
  "dependencies": {
    "react": "^18.2.0"
  }
}

詳細なパターンと実例

パターンの詳細なドキュメントは references/details.md にあります。上記の概要では不十分な場合は、このファイルをお読みください。

ベストプラクティス

1. バージョンの統一：ワークスペース全体で依存関係のバージョンを固定します
2. 設定の共有：ESLint、TypeScript、Prettier の設定を一元管理します
3. 依存関係グラフ：循環を避け、非循環に保ちます
4. キャッシュの効果的な活用：入力と出力を適切に設定します
5. 型安全性：フロントエンドとバックエンドの間で型を共有します
6. テスト戦略：パッケージではユニットテスト、アプリでは E2E テストを実施します
7. ドキュメント：各パッケージに README を用意します
8. リリース戦略：バージョン管理に changesets を使用します

よくある落とし穴

• 循環依存：A が B に依存し、B が A に依存する
• ファントム依存関係：package.json に記載されていない依存関係を使用する
• 不適切なキャッシュ入力：Turborepo の入力にファイルが不足している
• 過剰な共有：分離すべきコードを共有する
• 共有不足：パッケージ間でコードを重複させる
• 大規模なモノレポ：適切なツールがないと、ビルドが遅くなる

パッケージの公開

# Using Changesets
pnpm add -Dw @changesets/cli
pnpm changeset init

# Create changeset
pnpm changeset

# Version packages
pnpm changeset version

# Publish
pnpm changeset publish

# .github/workflows/release.yml
- name: Create Release Pull Request or Publish
  uses: changesets/action@v1
  with:
    publish: pnpm release
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}