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.

Clona 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 de la siguiente manera:

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 Nx ejecuta 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 que necesitaremos:

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 del cual podemos leer y escribir para crear o actualizar archivos del proyecto. No queremos tocar el sistema de archivos directamente, ya que no queremos hacer cambios si los usuarios ejecutan el generador en modo “dry-run”.

Notarás que el generador ya ha sido registrado 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 del nuevo procedimiento, usaremos una utilidad llamada generateFiles. Con esto, podemos definir una plantilla EJS que renderizaremos en nuestro generador con variables basadas en las opciones seleccionadas por el usuario.

Primero, definiremos 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, reemplazará las referencias a __<variable>__ en nombres de archivo/directorio con los valores proporcionados, y eliminará el .template del nombre del archivo.

El contenido de la plantilla es EJS, donde las variables se referencian usando la sintaxis <% ... %>.

En la plantilla, hicimos referencia a tres variables:

• procedureNameCamelCase
• procedureNameKebabCase
• procedureType

Así que necesitamos asegurarnos de pasar esas variables a generateFiles, junto con el directorio donde generar los archivos, específicamente la ubicación de los archivos fuente (es decir, sourceRoot) para el proyecto tRPC seleccionado por el usuario como entrada del generador, que podemos extraer de la configuración del proyecto.

Actualicemos el generador para hacer 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';

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

También llamamos a formatFilesInSubtree al final del generador, lo que asegura que cualquier archivo que creemos o modifiquemos se formatee según la configuración de prettier del usuario.

Agrega el procedimiento al router

Luego, queremos que el generador conecte el nuevo procedimiento al router. ¡Esto implica leer y actualizar el código fuente del usuario!

Usamos manipulación de AST de TypeScript para actualizar las partes relevantes del archivo fuente. Hay algunos helpers llamados replace y destructuredImport para facilitar 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

En el fragmento de código anterior, replace usa un selector tsquery para encontrar el argumento agregado a la función router.

Puedes usar el tsquery playground como una herramienta útil para probar diferentes selectores.

Ahora que hemos implementado el generador, compilémoslo para asegurarnos de que esté disponible para probarlo en nuestro proyecto de aventura dungeon.

pnpm nx run @aws/nx-plugin:compile

Probando el generador

Para probar el generador, vincularemos nuestro Nx Plugin for AWS local a una base de código existente.

Crea un proyecto de prueba con una API tRPC

Nota

Si has completado el tutorial de aventura dungeon, o ya tienes otro workspace Nx existente que usa una API tRPC, puedes saltar este paso.

En un directorio separado, crea un nuevo workspace de prueba:

pnpm

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

yarn

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

npm

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

bun

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

Luego, generemos una API tRPC para agregar el procedimiento:

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 nuestro Nx Plugin for AWS local

En tu base de código, vinculamos nuestro @aws/nx-plugin local:

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

Observa que vinculamos al plugin compilado en dist/packages/nx-plugin en lugar del código fuente.

Ejecuta el nuevo generador

Probemos el nuevo 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 nuevo generador en la lista en VSCode, quizás necesites refrescar el workspace Nx:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Si tiene éxito, deberíamos haber generado un nuevo procedimiento y agregado el procedimiento a nuestro router en router.ts.

Ejercicios

Si has llegado hasta aquí y aún tienes tiempo para experimentar con generadores Nx, aquí hay algunas sugerencias de características para agregar al generador de procedimientos:

1. Operaciones anidadas

Intenta actualizar el generador para soportar routers anidados:

• Aceptando notación de puntos para la entrada procedure (ej. games.query)
• Generando un procedimiento con nombre basado en la notación de puntos invertida (ej. queryGames)
• ¡Agregando el router anidado apropiado (o actualizándolo si ya existe)!

2. Validación

Nuestro generador debería prevenir problemas potenciales, como que un usuario seleccione un project que no sea una API tRPC. Mira el generador api-connection para ver un ejemplo de esto.

3. Pruebas unitarias

Escribe algunas pruebas unitarias para el generador. Son bastante sencillas de implementar y la mayoría sigue el flujo general:

1. Crea un workspace tree vacío usando createTreeUsingTsSolutionSetup()
2. Agrega cualquier archivo que deba existir previamente en el tree (ej. project.json y src/router.ts para un backend tRPC)
3. Ejecuta el generador bajo prueba
4. Valida que los cambios esperados se realicen en el tree

4. Pruebas end-to-end

Actualmente tenemos una sola “prueba de humo” que ejecuta todos los generadores y verifica que la construcción tenga éxito. Esto debería actualizarse para incluir el nuevo generador.