nx-generate

运行 Nx 生成器

Nx 生成器是强大的工具，可用于搭建项目、执行自动化代码迁移，或在单体仓库中自动完成重复性任务。它们可确保整个代码库保持一致，并减少样板工作。

当用户想要执行以下操作时，使用此技能：

• 创建新的项目，例如库或应用程序
• 搭建功能或样板代码
• 运行工作区专属或自定义生成器
• 执行其他任何有对应 Nx 生成器的操作

关键原则

1. 始终使用 --no-interactive——避免提示导致执行挂起
2. 阅读生成器源代码——仅查看 schema 并不足够；要了解生成器实际执行的操作
3. 遵循现有仓库模式——研究仓库中的类似产物，并遵循其约定
4. 使用 lint/test/build/typecheck 等进行验证——生成的代码必须通过验证。列出的目标仅为示例，请根据此工作区选择合适的目标。

步骤

1. 查找可用生成器

使用 Nx CLI 查找可用生成器：

• 列出某个插件的所有生成器：npx nx list @nx/react
• 查看可用插件：npx nx list

其中包括插件生成器（例如 @nx/react:library）和本地工作区生成器。

2. 根据用户请求选择生成器

确定哪些生成器可以满足用户需求。考虑用户需要的产物类型、相关框架，以及用户提到的任何特定生成器名称。

重要：如果本地工作区生成器和外部插件生成器都能满足请求，始终优先选择本地工作区生成器。本地生成器针对特定仓库的模式进行了定制。

如果没有合适的生成器，可以停止使用此技能。不过，作出这一判断需要充分依据——在确定没有适用生成器之前，请仔细考虑所有可用生成器。

3. 获取生成器选项

使用 --help 标志了解可用选项：

npx nx g @nx/react:library --help

留意必需选项、可能需要覆盖的默认值，以及与用户请求相关的选项。

库的可构建性

默认使用不可构建库，除非有明确理由需要选择可构建库。

类型	适用场景	生成器标志
不可构建（默认）	由应用消费的单体仓库内部库	不使用 --bundler 标志
可构建	发布到 npm、跨仓库共享、需要稳定库以提升缓存命中率	--bundler=vite 或 --bundler=swc

不可构建库：

• 直接导出 .ts/.tsx 源代码
• 由使用方的打包器编译
• 开发体验更快，配置更少

可构建库：

• 拥有自己的构建目标
• 适用于很少变更的稳定库（缓存命中）
• 发布到 npm 的必要条件

如果不确定，请询问用户：“此库应当是可构建库（拥有独立构建步骤，缓存效果更好），还是不可构建库（直接消费源代码，配置更简单）？”

4. 阅读生成器源代码

这一步至关重要。 仅凭 schema 无法了解所有信息。阅读源代码有助于你：

• 准确了解将创建或修改哪些文件，以及文件所在位置
• 了解副作用（更新配置、安装依赖等）
• 找出 schema 中不明显的行为和选项
• 了解各选项之间的交互方式

查找生成器源代码：

• 对于插件生成器：使用 node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));" 查找 generators.json，然后从中定位源代码
• 如果此方法无效，直接读取 node_modules/<plugin>/generators.json
• 对于本地生成器：通常位于 tools/generators/ 或本地插件目录中。搜索代码库，查找生成器名称。

阅读源代码后，重新考虑：这是合适的生成器吗？如果不是，请返回第 2 步。

⚠️ --directory 标志的行为可能会造成误解。 它应指定生成的库或组件的完整路径，而不是其将生成到的父路径。

# ✅ 正确 - directory 是库的完整路径
nx g @nx/react:library --directory=libs/my-lib
# 生成 libs/my-lib/package.json 等文件

# ❌ 错误 - 这会在 libs 和 libs/src/... 中创建文件
nx g @nx/react:library --name=my-lib --directory=libs
# 生成 libs/package.json 等文件

5. 检查现有模式

生成之前，请检查代码库中的目标区域：

• 查看类似的现有产物（其他库、应用等）
• 找出命名约定、文件结构和配置模式
• 注意使用了哪些测试运行器、构建工具和代码检查工具
• 配置生成器，使其符合这些模式

6. 试运行以验证文件位置

务必先使用 --dry-run 运行，以验证文件会在正确的位置创建：

npx nx g @nx/react:library --directory=libs/my-lib --dry-run --no-interactive

仔细检查输出。如果文件会创建在错误的位置，请根据从生成器源代码中了解到的信息调整选项。

注意：有些生成器不支持试运行（例如，它们会安装 npm 包）。如果因此导致试运行失败，请直接实际运行生成器。

7. 运行生成器

执行生成器：

nx generate <generator-name> <options> --no-interactive

提示： 新包通常需要配置工作区依赖（例如，导入共享类型、供应用使用）。link-workspace-packages 技能可以帮助正确添加这些依赖。

8. 修改生成的代码（如有需要）

生成器提供了一个起点。请根据需要修改输出，以便：

• 按要求添加或修改功能
• 调整导入、导出或配置
• 与现有代码模式集成

重要提示： 如果替换或删除生成的测试文件（例如 *.spec.ts），请编写有意义的替代测试，或者从项目配置中移除 test 目标。空测试套件会导致 nx test 失败。

9. 格式化并验证

格式化所有生成或修改的文件：

nx format --fix

此示例使用内置的 nx 格式化功能和 prettier。此工作区可能还会使用其他格式化工具，请在合适时使用这些工具。

然后验证生成的代码是否正常运行。请注意，使用生成器进行的更改或后续修改可能会影响多个项目，因此通常仅运行刚创建产物的目标并不足够。

# these targets are just an example!
nx run-many -t build,lint,test,typecheck

这些目标是许多工作区中常见的示例。你应当研究此工作区及其项目中还有哪些可用目标。CI 配置通常是了解必须通过哪些关键目标的好参考。

如果验证因可处理的问题而失败（少量代码检查错误、轻微类型问题），请修复这些问题。如果问题很多，请先尝试明显可行的修复，然后向用户说明生成了什么、哪些部分失败，以及你尝试过哪些方法。