nx-monorepo

Nx モノレポ

概要

TypeScript／JavaScript プロジェクトにおける Nx モノレポの管理方法を案内します。ワークスペースの作成、プロジェクトの生成、タスクの実行、キャッシュ戦略、Module Federation、CI/CD との統合について説明します。

使用する場面

次の場合にこのスキルを使用します。

• 新しい Nx ワークスペースを作成する場合、または既存のプロジェクトで Nx を初期化する場合
• Nx ジェネレーターを使用してアプリケーション、ライブラリ、コンポーネントを生成する場合
• 影響を受けるプロジェクト向けのコマンドを実行する場合、または複数のプロジェクトにまたがってタスクを実行する場合
• Nx プロジェクト用の CI/CD パイプライン（GitHub Actions、CircleCI など）を設定する場合
• React または Next.js で Module Federation を設定する場合
• Nx 内で NestJS バックエンドアプリケーションを実装する場合
• ビルド可能および公開可能なライブラリで 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 library
   nx g @nx/react:lib my-lib
   
   # TypeScript library
   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. すべてのプロジェクトに対してタスクを実行します。

   # Build all projects
   nx run-many -t build
   
   # Test specific projects
   nx run-many -t test -p=my-app,my-lib
   
   # Test by pattern
   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 では影響を受けるプロジェクト向けのコマンドを使用し、変更されたプロジェクトのみをビルド／テストします。

# .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
# Select: Integrated Monorepo → React → Integrated monorepo (Nx Cloud)

確認： cd my-workspace && nx show projects に作成されたアプリが表示されます。

期待される結果： 次の内容を備えたワークスペースが作成されます。

• React アプリを含む apps/ ディレクトリ
• 共有ライブラリ用の libs/ ディレクトリ
• キャッシュ設定を含む nx.json
• すぐに使用できる CI/CD ワークフローファイル

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

入力：「最近の変更によって影響を受けたプロジェクトだけテストして」

コマンド：

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

期待される結果： コミット間の変更によって影響を受けたプロジェクトのテストのみが実行され、前回の実行結果がキャッシュから活用されます。

例 3：共有ライブラリの生成とビルド

入力：「共有 UI ライブラリを作成して、アプリで使用して」

手順：

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

# Generate component in library
nx g @nx/react:component button --project=shared-ui

# Import in app (tsconfig paths auto-configured)
import { Button } from '@my-workspace/shared-ui'

確認： nx run shared-ui:build が正常に完了し、nx graph にアプリへの依存関係が表示されます。

期待される結果： 適切な TypeScript パスマッピングが設定された、libs/shared-ui 内のビルド可能なライブラリが作成されます。

例 4：Module Federation の設定

入力：「マイクロフロントエンド用に Module Federation を設定して」

手順：

# Create host app
nx g @nx/react:host dashboard

# Add remote to host
nx g @nx/react:remote product-catalog --host=dashboard

# Start dev servers
nx run dashboard:serve
nx run product-catalog:serve

確認： 両方のサーバーがエラーなく起動し、nx graph に dashboard → product-catalog のリモート接続が表示されます。

期待される結果： product-catalog が実行時に dashboard に動的に読み込まれる、2 つの独立したアプリケーションが稼働します。

例 5：ビルドの依存関係をデバッグする

入力：「関係のない lib が変更されたときに、アプリが再ビルドされるのはなぜですか？」

診断：

# Show project graph
nx graph --focused=my-app

# Check implicit dependencies
nx show project my-app --json | grep implicitDependencies

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

修正を確認する： 関係のない lib に変更を加え、nx affected -t build を実行します。影響を受けるプロジェクトの一覧に my-app が表示されないはずです。

ベストプラクティス

• CI では常に nx affected を使用し、 変更されたプロジェクトのみをテスト／ビルドします
• 技術レイヤーではなく、ドメイン／ビジネス機能ごとに lib を整理します
• タグを一貫して使用します（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、Expo のパターン	references/react.md
NestJS バックエンドのパターン	references/nestjs.md
TypeScript パッケージ	references/typescript.md
CI/CD（GitHub、CircleCI など）	references/ci-cd.md
キャッシュ、affected、高度なトピック	references/advanced.md