nx の使い方完全ガイド — モノレポ管理の中核ツール

一言でいうと

Nx は、モノレポ（monorepo）環境におけるプロジェクト管理・ビルド・タスク実行を高速かつ効率的に行うためのビルドシステム兼CLIツールです。プロジェクトグラフの自動解析、タスクの並列実行、キャッシュによるビルド高速化を提供し、大規模なコードベースの開発体験を劇的に改善します。

どんな時に使う？

1. 複数のアプリ・ライブラリを1つのリポジトリで管理したい時 フロントエンド（React / Angular / Vue）とバックエンド（Node / NestJS）を同一リポジトリで開発し、共通ライブラリを共有するようなケースに最適です。

2. CIのビルド時間を短縮したい時 変更の影響を受けたプロジェクトだけをビルド・テストする「affected」コマンドや、ローカル／リモートキャッシュにより、CIパイプラインの実行時間を大幅に削減できます。

3. コードベースの依存関係を可視化・統制したい時 プロジェクトグラフを自動生成し、モジュール間の依存関係を可視化できます。モジュール境界ルール（Module Boundary Rules）で意図しない依存を防止することも可能です。

インストール

# npm
npm install -D nx

# yarn
yarn add -D nx

# pnpm
pnpm add -D nx

新規ワークスペースの作成（推奨）

# 対話形式で新規ワークスペースを作成
npx create-nx-workspace@latest my-workspace

補足: 既存のnpm/yarn/pnpmワークスペースにNxを後から追加することも可能です。その場合は npx nx@latest init を実行します。

基本的な使い方

ワークスペースの初期化と基本コマンド

// nx.json（ワークスペースのルート設定ファイル）
{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "cache": true
    },
    "test": {
      "cache": true
    },
    "lint": {
      "cache": true
    }
  },
  "defaultBase": "main"
}

# 特定プロジェクトのビルド
npx nx build my-app

# 特定プロジェクトのテスト
npx nx test my-lib

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

# すべてのプロジェクトでlintを実行
npx nx run-many -t lint

# プロジェクトグラフを可視化（ブラウザで開く）
npx nx graph

project.json によるプロジェクト定義

// apps/my-app/project.json
{
  "name": "my-app",
  "sourceRoot": "apps/my-app/src",
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "outputPath": "dist/apps/my-app",
        "main": "apps/my-app/src/main.ts",
        "tsConfig": "apps/my-app/tsconfig.app.json"
      },
      "configurations": {
        "production": {
          "optimization": true,
          "sourceMap": false
        }
      }
    },
    "serve": {
      "executor": "@nx/webpack:dev-server",
      "options": {
        "buildTarget": "my-app:build"
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "apps/my-app/jest.config.ts"
      }
    }
  }
}

よく使うAPI・コマンド

1. nx affected — 変更影響範囲の自動検出

Git の差分を解析し、変更の影響を受けたプロジェクトだけを対象にタスクを実行します。CIでの利用が特に効果的です。

# mainブランチとの差分で影響を受けたプロジェクトをビルド
npx nx affected -t build --base=main --head=HEAD

# 影響を受けたプロジェクトのテストとlintを同時に実行
npx nx affected -t test lint

# 影響を受けたプロジェクト一覧を表示（実行はしない）
npx nx show projects --affected

2. nx run-many — 複数プロジェクトへの一括タスク実行

# 全プロジェクトのビルド
npx nx run-many -t build

# 特定プロジェクトだけを対象に
npx nx run-many -t build -p my-app,my-lib

# 並列度を指定（デフォルトはCPUコア数に応じて自動調整）
npx nx run-many -t test --parallel=5

# 複数ターゲットを同時に
npx nx run-many -t build test lint

3. nx graph — プロジェクト依存グラフの可視化

# ブラウザでインタラクティブなグラフを表示
npx nx graph

# 影響を受けたプロジェクトだけをグラフ表示
npx nx affected:graph

# JSON形式で出力（CI連携やスクリプト処理向け）
npx nx graph --file=output.json

4. nx generate — コード生成（ジェネレーター）

プラグインが提供するジェネレーターを使い、ボイラープレートを自動生成します。

# Reactアプリケーションの生成（@nx/reactプラグインが必要）
npx nx generate @nx/react:application my-new-app

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

# コンポーネントの生成
npx nx generate @nx/react:component my-button --project=my-app

# dry-runで変更内容を事前確認
npx nx generate @nx/react:library ui-kit --dry-run

5. nx release — バージョニングとリリース管理

モノレポ内のパッケージのバージョン管理・CHANGELOG生成・npm publishを統合的に行います。

// nx.json に追加
{
  "release": {
    "projects": ["packages/*"],
    "version": {
      "conventionalCommits": true
    },
    "changelog": {
      "workspaceChangelog": {
        "createRelease": "github"
      }
    }
  }
}

# バージョンの更新
npx nx release version minor

# CHANGELOG生成
npx nx release changelog

# npm publish
npx nx release publish

# 上記すべてを一括実行
npx nx release --first-release

類似パッケージとの比較

補足: Lerna v6以降はNxをバックエンドとして内蔵しています。Lernaの既存ユーザーは自然にNxの恩恵を受けられます。

注意点・Tips

1. キャッシュの仕組みを正しく理解する

// nx.json — キャッシュ対象の入出力を明示的に定義
{
  "targetDefaults": {
    "build": {
      "cache": true,
      "inputs": [
        "{projectRoot}/**/*",
        { "externalDependencies": ["webpack"] }
      ],
      "outputs": ["{options.outputPath}"]
    }
  }
}

inputs と outputs を正確に設定しないと、キャッシュが効かない、あるいは古いキャッシュが使われるといった問題が発生します。環境変数やビルド設定ファイルの変更もキャッシュキーに含めるべきかを検討してください。

2. nx.json と project.json の使い分け

• nx.json: ワークスペース全体の設定（デフォルトのターゲット設定、キャッシュポリシー、プラグイン設定）
• project.json: 個別プロジェクトの設定（ターゲット定義、executor指定）
• package.json: project.json の代わりに package.json の scripts をNxのターゲットとして推論させることも可能（Package-Based Repos）

3. Nx Cloud でリモートキャッシュを活用する

# Nx Cloudの接続設定
npx nx connect

チーム全体でビルドキャッシュを共有でき、「同僚がすでにビルドしたものを再ビルドしない」という体験が得られます。CIの実行時間が劇的に短縮されるケースが多いです。

4. Integrated Repos vs Package-Based Repos

Nxには2つのアプローチがあります。

• Integrated（統合型）: project.json でターゲットを定義し、Nxプラグインのexecutorを使う。最大限の機能を活用可能。
• Package-Based: 既存の package.json の scripts をそのまま利用。既存プロジェクトへの段階的導入に最適。

既存のモノレポに導入する場合は、まずPackage-Basedで始めて段階的にIntegratedへ移行するのが現実的です。

5. nx reset を覚えておく

# キャッシュとNx Daemonをリセット
npx nx reset

ビルドが不安定になった場合やキャッシュの不整合が疑われる場合に有効です。トラブルシューティングの第一歩として覚えておいてください。

6. TypeScript のパスエイリアスに注意

モノレポ内のライブラリ参照は tsconfig.base.json のパスエイリアスで管理されます。ジェネレーターが自動設定しますが、手動でライブラリを追加した場合は設定漏れに注意してください。

// tsconfig.base.json
{
  "compilerOptions": {
    "paths": {
      "@my-org/shared-utils": ["libs/shared-utils/src/index.ts"],
      "@my-org/ui-kit": ["libs/ui-kit/src/index.ts"]
    }
  }
}

まとめ

Nxは単なるモノレポツールではなく、プロジェクトグラフの自動解析・タスクの並列実行・インテリジェントなキャッシュ・コード生成を統合したビルドシステムです。学習コストはやや高いものの、プロジェクト規模が大きくなるほどその恩恵は大きく、CI時間の短縮やコードベースの秩序維持に直結します。既存プロジェクトには npx nx@latest init で段階的に導入できるため、まずはキャッシュとaffectedコマンドの効果を体感するところから始めてみてください。

この記事はNx v22.6.4時点の情報に基づいています。 Nxは活発に開発されており、メジャーバージョン間でCLIオプションや設定形式が変更される場合があります。公式ドキュメント（https://nx.dev）も併せて参照してください。