贡献生成器

让我们为@aws/nx-plugin创建一个新的生成器，目标是为tRPC API生成新的过程（procedure）。

检出插件

首先克隆插件仓库：

git clone git@github.com:awslabs/nx-plugin-for-aws.git

安装依赖并构建：

cd nx-plugin-for-aws
pnpm i
pnpm nx run-many --target build --all

创建空生成器

在packages/nx-plugin/src/trpc/procedure目录下创建新生成器。

我们提供了创建生成器的生成器，可以快速搭建新生成器！运行以下命令：

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#nx-generator
5. 填写必需参数
   • pluginProject: @aws/nx-plugin
   • name: ts#trpc-api#procedure
   • directory: trpc/procedure
   • description: Adds a procedure to a tRPC API
6. 点击 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API

npm

npx nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API --dry-run

以下文件已自动生成：

• 文件夹packages/nx-plugin/src/trpc/procedure

  • schema.json 定义生成器的输入模式
  • schema.d.ts 与模式匹配的TypeScript接口
  • generator.ts Nx运行的生成器函数
  • generator.spec.ts 生成器测试
• 文件夹docs/src/content/docs/guides/

  • trpc-procedure.mdx 生成器文档
• packages/nx-plugin/generators.json 更新包含新生成器

更新模式文件添加所需属性：

schema.json

{
  "$schema": "https://json-schema.org/schema",
  "$id": "tRPCProcedure",
  "title": "Adds a procedure to a tRPC API",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "description": "tRPC API项目",
      "x-prompt": "选择要添加过程的tRPC API项目",
      "x-dropdown": "projects",
      "x-priority": "important"
    },
    "procedure": {
      "description": "新过程名称",
      "type": "string",
      "x-prompt": "请输入新过程名称",
      "x-priority": "important",
    },
    "type": {
      "description": "生成的过程类型",
      "type": "string",
      "x-prompt": "请选择过程类型",
      "x-priority": "important",
      "default": "query",
      "enum": ["query", "mutation"]
    }
  },
  "required": ["project", "procedure"]
}

schema.d.ts

export interface TrpcProcedureSchema {
  project: string;
  procedure: string;
  type: 'query' | 'mutation';
}

注意

注意生成器的输入包含一个Tree对象和我们模式中定义的选项。Tree本质上是虚拟文件系统，可用于读写项目文件。我们不直接操作文件系统，因为用户可能在”dry-run”模式下运行生成器。

生成器已自动注册到packages/nx-plugin/generators.json：

 ...
  "generators": {
    ...
    "ts#trpc-api#procedure": {
      "factory": "./src/trpc/procedure/generator",
      "schema": "./src/trpc/procedure/schema.json",
      "description": "Adds a procedure to a tRPC API"
    }
  },
...

实现生成器

要实现tRPC API过程添加，需要完成两个步骤：

1. 创建新过程的TypeScript文件
2. 将过程添加到路由

创建新过程

使用generateFiles工具创建TypeScript文件。我们可以定义EJS模板，根据用户选项渲染生成内容。

模板文件位于packages/nx-plugin/src/trpc/procedure/files/procedures/__procedureNameKebabCase__.ts.template：

files/procedures/__procedureNameKebabCase__.ts.template

import { publicProcedure } from '../init.js';
import { z } from 'zod/v4';

export const <%- procedureNameCamelCase %> = publicProcedure
  .input(z.object({
    // TODO: 定义输入
  }))
  .output(z.object({
    // TODO: 定义输出
  }))
  .<%- procedureType %>(async ({ input, ctx }) => {
    // TODO: 实现逻辑
    return {};
  });

提示

generateFiles处理模板时会替换文件名中的__<variable>__占位符，并去除.template后缀。模板内容使用EJS语法，通过<% ... %>引用变量。

模板中引用了三个变量：

• procedureNameCamelCase
• procedureNameKebabCase
• procedureType

我们需要将这些变量传递给generateFiles，并确定生成文件的目标目录（即用户选择的tRPC项目的源码根目录）：

procedure/generator.ts

import {
  generateFiles,
  joinPathFragments,
  readProjectConfiguration,
  Tree,
} from '@nx/devkit';
import { TrpcProcedureSchema } from './schema';
import { formatFilesInSubtree } from '../../utils/format';
import camelCase from 'lodash.camelcase';
import kebabCase from 'lodash.kebabcase';

export const trpcProcedureGenerator = async (
  tree: Tree,
  options: TrpcProcedureSchema,
) => {
  const projectConfig = readProjectConfiguration(tree, options.project);

  const procedureNameCamelCase = camelCase(options.procedure);
  const procedureNameKebabCase = kebabCase(options.procedure);

  generateFiles(
    tree,
    joinPathFragments(__dirname, 'files'),
    projectConfig.sourceRoot,
    {
      procedureNameCamelCase,
      procedureNameKebabCase,
      procedureType: options.type,
    },
  );

  await formatFilesInSubtree(tree);
};

export default trpcProcedureGenerator;

提示

最后调用formatFilesInSubtree确保生成/修改的文件符合用户的prettier配置。

将过程添加到路由

接下来需要更新路由文件。我们使用TypeScript AST操作来修改源码：

procedure/generator.ts

import {
  generateFiles,
  joinPathFragments,
  readProjectConfiguration,
  Tree,
} from '@nx/devkit';
import { TrpcProcedureSchema } from './schema';
import { formatFilesInSubtree } from '../../utils/format';
import camelCase from 'lodash.camelcase';
import kebabCase from 'lodash.kebabcase';
import { destructuredImport, replace } from '../../utils/ast';
import { factory, ObjectLiteralExpression } from 'typescript';

export const trpcProcedureGenerator = async (
  tree: Tree,
  options: TrpcProcedureSchema,
) => {
  const projectConfig = readProjectConfiguration(tree, options.project);

  const procedureNameCamelCase = camelCase(options.procedure);
  const procedureNameKebabCase = kebabCase(options.procedure);

  generateFiles(
    tree,
    joinPathFragments(__dirname, 'files'),
    projectConfig.sourceRoot,
    {
      procedureNameCamelCase,
      procedureNameKebabCase,
      procedureType: options.type,
    },
  );

  const routerPath = joinPathFragments(projectConfig.sourceRoot, 'router.ts');

  destructuredImport(
    tree,
    routerPath,
    [procedureNameCamelCase],
    `./procedures/${procedureNameKebabCase}.js`,
  );

  replace(
    tree,
    routerPath,
    'CallExpression[expression.name="router"] > ObjectLiteralExpression',
    (node) =>
      factory.createObjectLiteralExpression([
        ...(node as ObjectLiteralExpression).properties,
        factory.createShorthandPropertyAssignment(procedureNameCamelCase),
      ]),
  );

  await formatFilesInSubtree(tree);
};

export default trpcProcedureGenerator;

提示

replace使用tsquery选择器定位router函数的参数。可以使用tsquery playground测试选择器。

编译生成器使其可用：

pnpm nx run @aws/nx-plugin:compile

测试生成器

创建测试项目

注意

如果已完成地牢冒险教程或有现成使用tRPC API的Nx工作区，可跳过此步骤。

创建新工作区：

pnpm

npx create-nx-workspace@~21.0.3 trpc-generator-test --pm=pnpm --preset=@aws/nx-plugin --ci=skip

yarn

npx create-nx-workspace@~21.0.3 trpc-generator-test --pm=yarn --preset=@aws/nx-plugin --ci=skip

npm

npx create-nx-workspace@~21.0.3 trpc-generator-test --pm=npm --preset=@aws/nx-plugin --ci=skip

bun

npx create-nx-workspace@~21.0.3 trpc-generator-test --pm=bun --preset=@aws/nx-plugin --ci=skip

生成tRPC API：

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#trpc-api
5. 填写必需参数
   • apiName: test-api
6. 点击 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive

npm

npx nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive --dry-run

链接本地插件

在测试项目中链接本地@aws/nx-plugin：

pnpm

cd path/to/trpc-generator-test
pnpm link path/to/nx-plugin-for-aws/dist/packages/nx-plugin

yarn

cd path/to/trpc-generator-test
yarn link path/to/nx-plugin-for-aws/dist/packages/nx-plugin

npm

cd path/to/trpc-generator-test
npm link path/to/nx-plugin-for-aws/dist/packages/nx-plugin

bun

cd path/to/nx-plugin-for-aws/dist/packages/nx-plugin
bun link
cd path/to/trpc-generator-test
bun link @aws/nx-plugin

注意

注意链接的是编译后的dist/packages/nx-plugin目录。

运行生成器

执行新生成器：

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#trpc-api#procedure
5. 填写必需参数
6. 点击 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api#procedure

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api#procedure

npm

npx nx g @aws/nx-plugin:ts#trpc-api#procedure

bun

bunx nx g @aws/nx-plugin:ts#trpc-api#procedure

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api#procedure --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api#procedure --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api#procedure --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api#procedure --dry-run

注意

如果在VSCode中看不到新生成器，可能需要刷新Nx工作区：

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

成功运行后，应生成新过程并更新router.ts文件。

扩展练习

1. 嵌套操作

支持通过点符号（如games.query）创建嵌套路由，生成反向命名的过程（如queryGames）

2. 输入验证

添加对非tRPC项目的防御性检查，参考api-connection生成器的实现

3. 单元测试

编写测试用例：

1. 使用createTreeUsingTsSolutionSetup()创建空工作区
2. 添加预置文件（如project.json和src/router.ts）
3. 运行生成器
4. 验证文件变更

4. 端到端测试

更新现有冒烟测试，包含新生成器的验证