name: nx-monorepo description: | Nx monorepo管理技能，适用于AI原生开发。当处理Nx工作空间、项目图、影响检测、代码生成和缓存时应使用此技能。使用场景包括：分析依赖关系、运行受影响命令、生成代码、配置Nx Cloud或优化构建性能。查询文档时调用nx-mcp工具。 version: “1.0.0”

Nx Monorepo

概述

此技能提供Nx monorepo管理的专家级能力。Nx是该AI原生平台的标准构建编排器，因其官方MCP服务器集成而被选用。

选择Nx的原因：官方MCP服务器、TypeScript原生支持、5分钟快速设置、为AI助手自动生成CLAUDE.md/AGENTS.md文件。

可用的MCP工具

nx_docs          - 查询Nx文档
nx_available_plugins - 列出官方Nx插件（默认未安装）

关键洞察：MCP提供文档查找功能。所有操作请使用Nx CLI。

核心CLI命令

项目图分析

# 查看交互式项目图
nx graph

# JSON输出供编程使用
nx graph --file=output.json

# 显示特定项目的依赖关系
nx graph --focus=my-app

# 显示依赖于此项目的项目
nx graph --affected

影响检测

# 自main分支以来哪些项目受影响？
nx affected -t build
nx affected -t test
nx affected -t lint

# 与特定基准比较
nx affected -t build --base=origin/main --head=HEAD

# 仅显示受影响项目
nx show projects --affected

运行任务

# 为所有项目运行任务
nx run-many -t build
nx run-many -t test

# 为特定项目运行
nx run-many -t build --projects=app-a,lib-b

# 控制并行度运行
nx run-many -t build --parallel=4

# 单个项目
nx build my-app
nx test my-lib

代码生成

# 列出可用生成器
nx list @nx/next
nx list @nx/react

# 生成新应用
nx g @nx/next:app my-app
nx g @nx/react:app my-frontend

# 生成库
nx g @nx/js:lib shared-utils
nx g @nx/react:lib ui-components

# 试运行（预览）
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"
      }
    }
  }
}

缓存

本地缓存

# 可缓存目标的缓存是自动的
nx build my-app  # 首次运行：执行
nx build my-app  # 第二次运行：缓存（瞬间完成）

# 清除缓存
nx reset

Nx Cloud（远程缓存）

# 连接到Nx Cloud
npx nx connect

# 或手动添加
nx g @nx/workspace:ci-workflow

# 验证连接
nx run-many -t build
# 查找："Remote cache hit"

缓存输入

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

常见模式

添加新的JS/TS应用

# 1. 添加插件（如果尚未安装）
pnpm nx add @nx/next    # 用于Next.js
pnpm nx add @nx/react   # 用于React
pnpm nx add @nx/node    # 用于Node/Express

# 2. 生成应用
pnpm nx g @nx/next:app dashboard --directory=apps/dashboard

# 3. 在图中验证
pnpm nx graph --focus=dashboard

# 4. 构建和运行
pnpm nx build dashboard
pnpm nx serve dashboard

添加Python应用（uv工作空间）

Python项目使用uv工作空间（类似于JS的pnpm工作空间），并手动为Nx创建project.json：

# 1. 创建目录并初始化
mkdir -p apps/my-python-app
cd apps/my-python-app
uv init
uv add --group dev pytest ruff mypy
cd ../..

# 2. 添加到uv工作空间（根目录pyproject.toml）

编辑根目录pyproject.toml：

[tool.uv.workspace]
members = [
    "apps/panaversity-fs-py",
    "apps/my-python-app",  # 在此处添加新项目
]

# 3. 从根目录同步所有Python依赖
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. 验证Nx识别它
pnpm nx show projects
pnpm nx graph --focus=my-python-app

# 5. 通过Nx运行任务
pnpm nx test my-python-app

共享Python库

创建多个Python应用可以导入的库：

mkdir -p libs/auth-common-py
cd libs/auth-common-py
uv init --lib
cd ../..
# 添加到工作空间成员，然后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库
pnpm nx g @nx/react:lib ui --directory=libs/shared/ui

# JS/TS工具库
pnpm nx g @nx/js:lib utils --directory=libs/shared/utils

# 领域库
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

      # 仅受影响构建
      - run: npx nx affected -t lint build test --base=origin/main

故障排除

“找不到项目”

# 重新生成项目图
nx reset
nx graph

缓存不工作

# 验证目标是否可缓存
cat nx.json | grep -A5 "targetDefaults"

# 检查输入是否稳定
nx build my-app --verbose

依赖问题

# 显示项目依赖关系
nx graph --focus=my-app

# 检查循环依赖
nx graph --file=graph.json
# 在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`

NxMonorepo管理技能Skill nx-monorepo