Nx Monorepo

概要

TypeScript/JavaScriptプロジェクトにおけるNxモノレポ管理のガイダンスを提供します。ワークスペース作成、プロジェクト生成、タスク実行、キャッシング戦略、Module Federation、CI/CD統合をカバーしています。

使用時期

以下の場合にこのスキルを使用してください：

• 新しいNxワークスペースの作成、または既存プロジェクトへのNx初期化
• Nxジェネレータでアプリケーション、ライブラリ、コンポーネントを生成
• affected コマンドの実行または複数プロジェクト間でのタスク実行
• Nxプロジェクト向けCI/CDパイプラインの設定（GitHub Actions、CircleCI等）
• React または Next.js での Module Federation 構成
• Nx内のNestJSバックエンドアプリケーション実装
• buildable/publishable ライブラリを含むTypeScriptパッケージライブラリの管理
• リモートキャッシングまたはNx Cloud設定
• モノレポのビルド時間とキャッシング戦略の最適化
• 依存グラフの問題や循環依存のデバッグ

トリガーフレーズ: "Nxワークスペース作成", "Nxモノレポ", "Nxアプリ生成", "Nx affected", "Nx CI/CD", "Module Federation Nx", "Nx Cloud"

手順

ワークスペース作成

1. 対話型セットアップで新しいワークスペースを作成:

   npx create-nx-workspace@latest
   

   プロンプトに従ってプリセット（Integrated、Standalone、Package-based）とフレームワークスタックを選択します。

2. 既存プロジェクトでNxを初期化:

   nx@latest init
   

3. 特定のプリセットで作成（非対話型）:

   npx create-nx-workspace@latest my-workspace --preset=react
   

   確認: nx show projects で新しいワークスペースプロジェクトが一覧表示されることを確認

プロジェクト生成

1. Reactアプリケーションを生成:

   nx g @nx/react:app my-app
   

2. ライブラリを生成:

   # Reactライブラリ
   nx g @nx/react:lib my-lib
   
   # TypeScriptライブラリ
   nx g @nx/js:lib my-util
   

   確認: nx show projects で新しいライブラリが一覧表示されることを確認

3. ライブラリ内にコンポーネントを生成:

   nx g @nx/react:component my-comp --project=my-lib
   

4. NestJSバックエンドを生成:

   nx g @nx/nest:app my-api
   

   確認: nx show projects で my-api が表示され、nx run my-api:build が成功することを確認

タスク実行

1. 影響を受けたプロジェクトのみタスク実行:

   nx affected -t lint test build
   

2. すべてのプロジェクト全体でタスク実行:

   # すべてのプロジェクトをビルド
   nx run-many -t build
   
   # 特定プロジェクトをテスト
   nx run-many -t test -p=my-app,my-lib
   
   # パターンでテスト
   nx run-many -t test --projects=*-app
   

3. 単一プロジェクトで特定のターゲットを実行:

   nx run my-app:build
   

4. 依存グラフを可視化:

   nx graph
   

プロジェクト設定

各プロジェクトには、ターゲット、エグゼキューター、設定を定義する project.json があります：

{
  "name": "my-app",
  "projectType": "application",
  "sourceRoot": "apps/my-app/src",
  "targets": {
    "build": {
      "executor": "@nx/react:webpack",
      "outputs": ["{workspaceRoot}/dist/apps/my-app"],
      "configurations": {
        "production": {
          "optimization": true
        }
      }
    },
    "test": {
      "executor": "@nx/vite:test"
    }
  },
  "tags": ["type:app", "scope:frontend"]
}

依存関係管理

1. プロジェクト依存関係を設定:

   {
     "targets": {
       "build": {
         "dependsOn": [
           { "projects": ["shared-ui"], "target": "build" }
         ]
       }
     }
   }
   

2. タグを組織化に使用:

   { "tags": ["type:ui", "scope:frontend", "platform:web"] }
   

Module Federation（Nx 17+）

1. リモート（マイクロフロントエンド）を生成:

   nx g @nx/react:remote checkout --host=dashboard
   

2. ホストを生成:

   nx g @nx/react:host dashboard
   

CI/CD設定

CI内で affected コマンドを使用して、変更されたプロジェクトのみをビルド/テストします：

# .github/workflows/ci.yml
- run: npx nx affected -t lint --parallel
- run: npx nx affected -t test --parallel
- run: npx nx affected -t build --parallel

例

例1: 新しいReactワークスペース作成

入力: 「ReactとTypeScriptで新しいNxワークスペースを作成してください」

手順:

npx create-nx-workspace@latest my-workspace
# 選択: Integrated Monorepo → React → Integrated monorepo (Nx Cloud)

確認: cd my-workspace && nx show projects で作成されたアプリが表示されることを確認

予想結果: 次を含むワークスペースが作成されます：

• apps/ ディレクトリ（Reactアプリ）
• libs/ ディレクトリ（共有ライブラリ用）
• キャッシング設定を含む nx.json
• CI/CDワークフローファイル

例2: 変更されたプロジェクトのテスト実行

入力: 「最近の変更の影響を受けたプロジェクトのみテストを実行してください」

コマンド:

nx affected -t test --base=main~1 --head=main

予想結果: コミット間の変更の影響を受けたプロジェクトのテストのみが実行され、以前の実行からのキャッシュされた結果が活用されます。

例3: 共有ライブラリを生成してビルド

入力: 「共有UIライブラリを作成してアプリで使用してください」

手順:

# ライブラリを生成
nx g @nx/react:lib shared-ui

# ライブラリ内にコンポーネントを生成
nx g @nx/react:component button --project=shared-ui

# アプリにインポート（tsconfigパスは自動設定）
import { Button } from '@my-workspace/shared-ui'

確認: nx run shared-ui:build が正常に完了し、nx graph がアプリへの依存関係リンクを表示することを確認

予想結果: libs/shared-ui に配置されたビルド可能ライブラリと、適切に構成されたTypeScriptパスマッピング。

例4: Module Federation を設定

入力: 「マイクロフロントエンド用にModule Federationを構成してください」

手順:

# ホストアプリを作成
nx g @nx/react:host dashboard

# ホストにリモートを追加
nx g @nx/react:remote product-catalog --host=dashboard

# 開発サーバーを起動
nx run dashboard:serve
nx run product-catalog:serve

確認: 両方のサーバーがエラーなく起動し、nx graph がdashboard → product-catalog リモート接続を表示することを確認

予想結果: 2つの独立したアプリケーションが実行され、product-catalogが実行時にdashboardに動的にロードされます。

例5: ビルド依存関係をデバッグ

入力: 「無関係なライブラリが変更されたときになぜアプリが再ビルドされるのですか？」

診断:

# プロジェクトグラフを表示
nx graph --focused=my-app

# 暗黙的な依存関係を確認
nx show project my-app --json | grep implicitDependencies

解決: 明示的な依存関係設定を追加するか、nx.json の namedInputs を使用してビルドをトリガーする特定のファイルを除外します。

修正確認: 無関係なライブラリに変更を加えて nx affected -t build を実行します — my-app は影響を受けたプロジェクト一覧に表示されません。

ベストプラクティス

• CIでは常に nx affected を使用 して、変更されたプロジェクトのみをテスト/ビルド
• ライブラリはドメイン/ビジネス機能で組織化（技術レイヤーではなく）
• タグを一貫して使用 （type:app|lib、scope:frontend|backend|shared）
• nx.json で workspaceLayout 境界を構成 して循環依存を防止
• Nx Cloudでリモートキャッシングを有効化 してチーム生産性を向上
• project.json を単純に保つ — 可能な場合は nx.json のデフォルトを使用
• 手動ファイル作成ではなくジェネレータを活用 して一貫性を確保
• namedInputs を構成 してテストファイルを本番キャッシュキーから除外
• マイクロフロントエンドの独立デプロイメント にModule Federationを使用
• ワークスペースジェネレータ を tools/ で保持してプロジェクト特有のスキャフォルディング用に

制約と警告

• Nx 17+ にはNode.js 18.10+ が必要
• Windowsユーザー: WSLまたはGit Bashの使用が最適
• 初回セットアップ はパッケージインストール時間により長くなる可能性
• 大規模モノレポ（50+プロジェクト）は分散タスク実行を使用すべき
• Module Federation にはwebpack 5+とNx固有の設定が必要
• 一部ジェネレータ は事前にプラグイン追加インストールが必要
• キャッシュ場所: デフォルト ~/.nx/cache は大きくなる可能性あり；必要に応じて nx.json で cacheDirectory を構成
• 循環依存 はビルド失敗の原因になります；可視化には nx graph を使用
• プリセット移行: Integrated/Standalone/Package-based間の変換には手動作業が必要

参照ファイル

特定のトピックについての詳細ガイダンスは以下を参照してください：

トピック	参照ファイル
ワークスペース設定、基本コマンド	references/basics.md
ジェネレータ（app、lib、component）	references/generators.md
React、Next.js、Exoパターン	references/react.md
NestJSバックエンドパターン	references/nestjs.md
TypeScriptパッケージ	references/typescript.md
CI/CD（GitHub、CircleCI等）	references/ci-cd.md
キャッシング、affected、高度なトピック	references/advanced.md