nx-monorepo

Nx Monorepo

概述

提供 TypeScript/JavaScript 项目中 Nx monorepo 管理的指导。涵盖工作区创建、项目生成、任务执行、缓存策略、Module Federation 和 CI/CD 集成。

适用场景

在以下情况使用此技能：

• 创建新的 Nx 工作区，或在现有项目中初始化 Nx
• 使用 Nx 生成器生成应用、库或组件
• 运行受影响项目命令，或跨多个项目执行任务
• 为 Nx 项目设置 CI/CD 流水线（GitHub Actions、CircleCI 等）
• 配置 React 或 Next.js 的 Module Federation
• 在 Nx 中实现 NestJS 后端应用
• 使用可构建和可发布的库管理 TypeScript 包
• 设置远程缓存或 Nx Cloud
• 优化 monorepo 构建时间和缓存策略
• 调试依赖关系图问题或循环依赖

触发短语：“创建 Nx 工作区”、“Nx monorepo”、“生成 Nx 应用”、“Nx 受影响项目”、“Nx CI/CD”、“Nx Module Federation”、“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 显示指向应用的依赖链接

**预期结果：**在 libs/shared-ui 中创建可构建的库，并配置好 TypeScript 路径映射。

示例 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 中。

示例 5：调试构建依赖项

输入：“为什么无关的库发生变化时，我的应用也会重新构建？”

诊断：

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

# Check implicit dependencies
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
生成器（应用、库、组件）	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
缓存、受影响项目、高级主题	references/advanced.md