Contribuir con un Generador

Vamos a crear un nuevo generador para contribuir a @aws/nx-plugin. Nuestro objetivo será generar un nuevo procedimiento para una API tRPC.

Clonar el Plugin

Primero, clonemos el plugin:

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

Luego, instalar y construir:

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

Crear un Generador Vacío

Creemos el nuevo generador en packages/nx-plugin/src/trpc/procedure.

¡Proveemos un generador para crear nuevos generadores para que puedas estructurar rápidamente el tuyo! Puedes ejecutar este generador así:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#nx-generator
5. Complete los parámetros requeridos
   • pluginProject: @aws/nx-plugin
   • name: ts#trpc-api#procedure
   • directory: trpc/procedure
   • description: Adds a procedure to a tRPC API
6. Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Notarás que se han generado los siguientes archivos:

• Directorypackages/nx-plugin/src/trpc/procedure

  • schema.json Define las entradas del generador
  • schema.d.ts Interfaz TypeScript que coincide con el schema
  • generator.ts Función que ejecuta Nx como generador
  • generator.spec.ts Pruebas para el generador
• Directorydocs/src/content/docs/guides/

  • trpc-procedure.mdx Documentación del generador
• packages/nx-plugin/generators.json Actualizado para incluir el generador

Actualicemos el schema para añadir las propiedades necesarias:

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 project",
      "x-prompt": "Select the tRPC API project to add the procedure to",
      "x-dropdown": "projects",
      "x-priority": "important"
    },
    "procedure": {
      "description": "The name of the new procedure",
      "type": "string",
      "x-prompt": "What would you like to call your new procedure?",
      "x-priority": "important",
    },
    "type": {
      "description": "The type of procedure to generate",
      "type": "string",
      "x-prompt": "What type of procedure would you like to generate?",
      "x-priority": "important",
      "default": "query",
      "enum": ["query", "mutation"]
    }
  },
  "required": ["project", "procedure"]
}

schema.d.ts

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

Nota

Observa que el generador recibe un Tree como entrada, junto con las opciones definidas en el schema. El Tree es esencialmente un sistema de archivos virtual donde podemos leer y escribir para crear o actualizar archivos del proyecto. No queremos modificar el sistema de archivos directamente, ya que no debemos hacer cambios si los usuarios ejecutan el generador en “modo de simulación”.

Notarás que el generador ya está configurado en 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"
    }
  },
...

Implementar el Generador

Para añadir un procedimiento a una API tRPC, necesitamos hacer dos cosas:

1. Crear un archivo TypeScript para el nuevo procedimiento
2. Añadir el procedimiento al enrutador

Crear el Nuevo Procedimiento

Para crear el archivo TypeScript, usaremos una utilidad llamada generateFiles. Con esta, definimos una plantilla EJS que podemos renderizar en nuestro generador con variables basadas en las opciones del usuario.

Primero, definamos la plantilla en 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: define input
  }))
  .output(z.object({
    // TODO: define output
  }))
  .<%- procedureType %>(async ({ input, ctx }) => {
    // TODO: implement!
    return {};
  });

Consejo

Cuando generateFiles procesa la plantilla, reemplaza referencias a __<variable>__ en nombres de archivos/directorios con los valores proporcionados, y elimina el .template del nombre del archivo.

El contenido de la plantilla usa EJS, donde las variables se referencian con <% ... %>.

En la plantilla, usamos tres variables:

• procedureNameCamelCase
• procedureNameKebabCase
• procedureType

Debemos asegurarnos de pasarlas a generateFiles, junto con el directorio destino (el sourceRoot del proyecto seleccionado), que podemos extraer de la configuración del proyecto.

Actualicemos el generador:

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;

Consejo

Llamamos a formatFilesInSubtree al final para formatear los archivos según la configuración de prettier del usuario.

Añadir el Procedimiento al Enrutador

Ahora actualizaremos el código fuente para incluir el nuevo procedimiento en el enrutador. Usamos manipulación de AST de TypeScript para esto:

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;

Consejo

El selector replace usa tsquery para encontrar el argumento de la función router.

Puedes usar el tsquery playground para probar selectores.

Compilemos el generador para probarlo:

pnpm nx run @aws/nx-plugin:compile

Probar el Generador

Para probar, vincularemos nuestro plugin local a un proyecto existente.

Crear Proyecto de Prueba con API tRPC

Nota

Si completaste el tutorial de dungeon adventure, o ya tienes un workspace Nx con API tRPC, puedes saltar este paso.

En otro directorio, crea un workspace:

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

Genera una API tRPC:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#trpc-api
5. Complete los parámetros requeridos
   • apiName: test-api
6. Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Vincular el Plugin Local

En tu proyecto, vincula @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

Nota

Vinculamos a la versión compilada en dist/packages/nx-plugin.

Ejecutar el Nuevo Generador

Prueba el generador:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#trpc-api#procedure
5. Complete los parámetros requeridos
6. Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Nota

Si no ves el generador en VSCode, refresca el workspace Nx:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Si tiene éxito, se habrá generado un nuevo procedimiento y se habrá añadido al enrutador en router.ts.

Ejercicios

Si llegaste hasta aquí y quieres explorar más, aquí algunas sugerencias:

1. Operaciones Anidadas

Modifica el generador para soportar enrutadores anidados:

• Aceptar notación de puntos para procedure (ej: games.query)
• Generar nombres basados en la notación inversa (ej: queryGames)
• Crear/actualizar enrutadores anidados

2. Validación

Añade validación para prevenir selección de proyectos no tRPC. Revisa el generador api-connection como referencia.

3. Pruebas Unitarias

Escribe pruebas unitarias que:

1. Creen un workspace vacío con createTreeUsingTsSolutionSetup()
2. Añadan archivos necesarios (ej: project.json, src/router.ts)
3. Ejecuten el generador
4. Verifiquen los cambios en el árbol

4. Pruebas End-to-End

Actualiza las pruebas existentes para incluir este nuevo generador. Actualmente hay una prueba básica que verifica que el build funciona.