nx-monorepo

Nx モノレポ

概要

このスキルでは、Nx モノレポ管理に関するエキスパートレベルの機能を提供します。Nx は、この AI ネイティブなプラットフォームの標準ビルドオーケストレーターです。

Nx を選ぶ理由：TypeScript ネイティブ、5 分でセットアップ、AI アシスタント向けに CLAUDE.md/AGENTS.md を自動生成、優れた CLI ツール。

ドキュメントの検索（オンデマンド MCP）

オンデマンド MCP を介して Nx ドキュメントを検索できます（永続サーバー不要、起動時トークン消費ゼロ）。

# Query Nx docs
bash scripts/nx-docs.sh "how to configure caching"
bash scripts/nx-docs.sh "affected command options"

# List available plugins
bash scripts/nx-plugins.sh

仕組み：スクリプトは stdio 経由で nx-mcp をオンデマンドで起動し、起動時トークンを消費する永続的な MCP 接続を回避します。

重要なポイント：操作には Nx CLI を、ドキュメント検索にはスクリプトを使用してください。

CLI の主なコマンド

プロジェクトグラフの分析

# View interactive project graph
nx graph

# JSON output for programmatic use
nx graph --file=output.json

# Show dependencies of specific project
nx graph --focus=my-app

# Show what depends on a project
nx graph --affected

影響範囲の検出

# What's affected since main?
nx affected -t build
nx affected -t test
nx affected -t lint

# Compare against specific base
nx affected -t build --base=origin/main --head=HEAD

# Show affected projects only
nx show projects --affected

タスクの実行

# Run task for all projects
nx run-many -t build
nx run-many -t test

# Run for specific projects
nx run-many -t build --projects=app-a,lib-b

# Run with parallelism control
nx run-many -t build --parallel=4

# Single project
nx build my-app
nx test my-lib

コード生成

# List available generators
nx list @nx/next
nx list @nx/react

# Generate new application
nx g @nx/next:app my-app
nx g @nx/react:app my-frontend

# Generate library
nx g @nx/js:lib shared-utils
nx g @nx/react:lib ui-components

# Dry run (preview)
nx g @nx/next:app my-app --dry-run

設定ファイル

nx.json（ワークスペース設定）

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "cache": true
    },
    "test": {
      "cache": true
    },
    "lint": {
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": ["default", "!{projectRoot}/**/*.spec.ts"]
  },
  "defaultBase": "main"
}

project.json（プロジェクト設定）

{
  "name": "my-app",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/my-app"
      }
    },
    "serve": {
      "executor": "@nx/next:server",
      "options": {
        "buildTarget": "my-app:build"
      }
    }
  }
}

キャッシュ

ローカルキャッシュ

# Cache is automatic for cacheable targets
nx build my-app  # First run: executes
nx build my-app  # Second run: cached (instant)

# Clear cache
nx reset

Nx Cloud（リモートキャッシュ）

# Connect to Nx Cloud
npx nx connect

# Or add manually
nx g @nx/workspace:ci-workflow

# Verify connection
nx run-many -t build
# Look for: "Remote cache hit"

キャッシュ入力

// In project.json or nx.json
{
  "targets": {
    "build": {
      "inputs": [
        "default",
        "^production",
        { "externalDependencies": ["next"] }
      ]
    }
  }
}

よく使われるパターン

新しい JS/TS アプリの追加

# 1. Add plugin (if not already installed)
pnpm nx add @nx/next    # For Next.js
pnpm nx add @nx/react   # For React
pnpm nx add @nx/node    # For Node/Express

# 2. Generate app
pnpm nx g @nx/next:app dashboard --directory=apps/dashboard

# 3. Verify in graph
pnpm nx graph --focus=dashboard

# 4. Build & Serve
pnpm nx build dashboard
pnpm nx serve dashboard

Python アプリの追加（uv ワークスペース）

Python プロジェクトでは、uv ワークスペース（JS の pnpm ワークスペースに相当）を使用し、Nx 用の project.json を手動で作成します。

# 1. Create directory and initialize
mkdir -p apps/my-python-app
cd apps/my-python-app
uv init
uv add --group dev pytest ruff mypy
cd ../..

# 2. Add to uv workspace (root pyproject.toml)

ルートの pyproject.toml を編集します。

[tool.uv.workspace]
members = [
    "apps/panaversity-fs-py",
    "apps/my-python-app",  # Add new project here
]

# 3. Sync all Python deps from root
uv sync --extra dev

apps/my-python-app/project.json（Nx 用）：

{
  "name": "my-python-app",
  "projectType": "application",
  "targets": {
    "build": {
      "command": "uv build",
      "options": { "cwd": "apps/my-python-app" }
    },
    "test": {
      "command": "uv run --extra dev pytest",
      "options": { "cwd": "apps/my-python-app" }
    },
    "lint": {
      "command": "uv run --extra dev ruff check .",
      "options": { "cwd": "apps/my-python-app" }
    }
  }
}

# 4. Verify Nx recognizes it
pnpm nx show projects
pnpm nx graph --focus=my-python-app

# 5. Run tasks via Nx
pnpm nx test my-python-app

Python 共有ライブラリ

複数の Python アプリからインポートできるライブラリを作成します。

mkdir -p libs/auth-common-py
cd libs/auth-common-py
uv init --lib
cd ../..
# Add to workspace members, then uv sync

依存するプロジェクトで参照します。

# apps/my-python-app/pyproject.toml
[project]
dependencies = ["auth-common-py"]

[tool.uv.sources]
auth-common-py = { workspace = true }

重要なポイント：uv はワークスペースを介して Python の依存関係を管理し、Nx はタスクをオーケストレーションします。ルートに uv.lock を 1 つだけ配置します。

共有ライブラリの作成

# JS/TS UI library
pnpm nx g @nx/react:lib ui --directory=libs/shared/ui

# JS/TS Utility library
pnpm nx g @nx/js:lib utils --directory=libs/shared/utils

# Domain library
pnpm nx g @nx/js:lib auth --directory=libs/domain/auth

CI パイプライン（GitHub Actions）

name: CI
on: [push, pull_request]

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
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      # Affected-only builds
      - run: npx nx affected -t lint build test --base=origin/main

トラブルシューティング

「プロジェクトが見つかりません」

# Regenerate project graph
nx reset
nx graph

キャッシュが機能しない

# Verify target is cacheable
cat nx.json | grep -A5 "targetDefaults"

# Check inputs are stable
nx build my-app --verbose

依存関係の問題

# Show project dependencies
nx graph --focus=my-app

# Check for circular deps
nx graph --file=graph.json
# Review edges in JSON

クイックリファレンス

タスク	コマンド
インタラクティブなグラフ	pnpm nx graph
影響を受けるプロジェクトのビルド	pnpm nx affected -t build
すべてのテストを実行	pnpm nx run-many -t test
JS/TS アプリを生成	pnpm nx g @nx/next:app name
JS/TS ライブラリを生成	pnpm nx g @nx/js:lib name
プラグインを追加	pnpm nx add @nx/next
キャッシュをクリア	pnpm nx reset
プロジェクトを表示	pnpm nx show projects
ジェネレーターを一覧表示	pnpm nx list @nx/next

Python 固有（uv）

タスク	コマンド
Python プロジェクトを初期化	cd apps/name && uv init
ランタイム依存関係を追加	uv add <package>
開発用依存関係を追加	uv add --group dev <package>
依存関係を同期	uv sync --extra dev
Nx 経由で実行	pnpm nx test my-python-app

関連スキル

• monorepo-workflow：PR のスタック化、トランクベース開発、コードレビュー
• monorepo-team-lead：CODEOWNERS、人間と AI のタスク振り分け、RFC プロセス