Contribuir con un Generador

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

Explora el Plugin

Primero, clonemos el plugin:

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

Luego instala y construye:

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

Crea 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 tu nuevo generador! 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 agregar 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 nuestro schema. El Tree es esencialmente un sistema de archivos virtual donde podemos leer y escribir para crear o actualizar archivos del proyecto. No queremos acceder directamente al sistema de archivos, ya que no queremos hacer cambios si los usuarios ejecutan el generador en modo “dry-run”.

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"
    }
  },
...

Implementa el Generador

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

1. Crear un archivo TypeScript para el nuevo procedimiento
2. Agregar el procedimiento al router

Crea el Nuevo Procedimiento

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

Primero, definimos 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';

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 .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). 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

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

Agrega el Procedimiento al Router

Ahora debemos actualizar el router para incluir el nuevo procedimiento. Usamos manipulación del AST de TypeScript para modificar el código fuente.

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 método replace usa un selector 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

Probando el Generador

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

Crea un 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

Vincula 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

Se vincula al plugin compilado en dist/packages/nx-plugin.

Ejecuta 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 agregado al router en router.ts.

Ejercicios

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

1. Operaciones Anidadas

Actualiza el generador para soportar routers anidados:

• Aceptar notación de puntos en procedure (ej: games.query)
• Generar procedimientos con nombres basados en la notación invertida (ej: queryGames)
• Agregar el router anidado correspondiente

2. Validación

El generador debe prevenir problemas, como seleccionar un project que no sea una API tRPC. Revisa el generador api-connection como ejemplo.

3. Pruebas Unitarias

Escribe pruebas unitarias para el generador. El flujo general es:

1. Crear un workspace vacío con createTreeUsingTsSolutionSetup()
2. Agregar archivos existentes necesarios (ej: project.json, src/router.ts)
3. Ejecutar el generador
4. Validar los cambios en el árbol

4. Pruebas End-to-End

Actualmente tenemos una prueba “smoke test” que verifica que los generadores se construyen. Debes actualizarla para incluir este nuevo generador.