nx-monorepo

Nx 单体仓库

概述

此技能提供管理 Nx 单体仓库的专家级能力。Nx 是这个 AI 原生平台的标准构建编排工具。

为何选择 Nx：原生支持 TypeScript，5 分钟即可完成设置，可为 AI 助手自动生成 CLAUDE.md/AGENTS.md，并提供出色的 CLI 工具。

文档查询（按需 MCP）

通过按需 MCP 查询 Nx 文档（无持久化服务，启动时消耗 0 个令牌）：

# 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。

创建共享库

# 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、人机任务分配、RFC 流程