Pular para o conteúdo
@aws/nx-plugin
Blog

Contribua com um Gerador

Vamos criar um novo gerador para contribuir com o @aws/nx-plugin. Nosso objetivo será gerar um novo procedimento para uma API tRPC.

Clonar o Plugin

Seção intitulada “Clonar o Plugin”

Primeiro, vamos clonar o plugin:

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

Em seguida, instalar e construir:

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

Criar um Gerador Vazio

Seção intitulada “Criar um Gerador Vazio”

Vamos criar o novo gerador em packages/nx-plugin/src/trpc/procedure.

Fornecemos um gerador para criar novos geradores, permitindo que você scaffold seu novo gerador rapidamente! Execute este gerador com:

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#nx-generator
  5. Preencha os parâmetros obrigatórios
    • pluginProject: @aws/nx-plugin
    • name: ts#trpc-api#procedure
    • directory: trpc/procedure
    • description: Adds a procedure to a tRPC API
  6. Clique em Generate

Os seguintes arquivos serão gerados para você:

  • Directorypackages/nx-plugin/src/trpc/procedure
    • schema.json Define as entradas do gerador
    • schema.d.ts Interface TypeScript correspondente ao schema
    • generator.ts Função executada pelo Nx como gerador
    • generator.spec.ts Testes para o gerador
  • Directorydocs/src/content/docs/guides/
    • trpc-procedure.mdx Documentação do gerador
  • packages/nx-plugin/generators.json Atualizado para incluir o gerador

Vamos atualizar o schema para adicionar as propriedades necessárias:

{
  "$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"]
}

O gerador já está configurado em 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 o Gerador

Seção intitulada “Implementar o Gerador”

Para adicionar um procedimento a uma API tRPC, precisamos:

  1. Criar um arquivo TypeScript para o novo procedimento
  2. Adicionar o procedimento ao router

Criar o Novo Procedimento

Seção intitulada “Criar o Novo Procedimento”

Usaremos o utilitário generateFiles com um template EJS para gerar o arquivo:

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 {};
  });

Atualizamos o gerador para passar as variáveis necessárias:

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;

Adicionar o Procedimento ao Router

Seção intitulada “Adicionar o Procedimento ao Router”

Usamos manipulação de AST para atualizar o arquivo do router:

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;

Compile o gerador para testar:

Terminal window
pnpm nx run @aws/nx-plugin:compile

Testar o Gerador

Seção intitulada “Testar o Gerador”

Criar Projeto de Teste

Seção intitulada “Criar Projeto de Teste”

Crie um novo workspace:

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

Gere uma API tRPC:

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#trpc-api
  5. Preencha os parâmetros obrigatórios
    • apiName: test-api
  6. Clique em Generate

Vincular o Plugin Local

Seção intitulada “Vincular o Plugin Local”

Vincule o @aws/nx-plugin local:

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

Executar o Gerador

Seção intitulada “Executar o Gerador”

Execute o novo gerador:

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#trpc-api#procedure
  5. Preencha os parâmetros obrigatórios
    • Clique em Generate

    Exercícios

    Seção intitulada “Exercícios”

    Sugestões para aprimorar o gerador:

    1. Operações Aninhadas

    Seção intitulada “1. Operações Aninhadas”
    • Aceitar notação com pontos para procedure (ex: games.query)
    • Gerar procedimentos com nomes baseados na notação invertida
    • Criar routers aninhados

    2. Validação

    Seção intitulada “2. Validação”
    • Impedir seleção de projetos não-tRPC
    • Ver exemplos no gerador connection

    3. Testes Unitários

    Seção intitulada “3. Testes Unitários”
    1. Criar workspace vazio com createTreeUsingTsSolutionSetup()
    2. Adicionar arquivos pré-existentes
    3. Executar gerador
    4. Validar alterações

    4. Testes End-to-End

    Seção intitulada “4. Testes End-to-End”
    • Atualizar smoke tests para incluir o novo gerador
    • Verificar se a build continua funcionando

    Orientação Geral para Acelerar Contribuições

    Seção intitulada “Orientação Geral para Acelerar Contribuições”

    Esta seção contém algumas orientações gerais que podem ajudar ao trabalhar no Nx Plugin for AWS.

    Trabalhe de trás para frente a partir de um projeto real

    Seção intitulada “Trabalhe de trás para frente a partir de um projeto real”

    Uma forma útil de construir novos geradores ou adicionar recursos/correções a um gerador existente é construí-lo de verdade primeiro. Dessa forma, você pode validar suas ideias e iterar rapidamente para alcançar a funcionalidade necessária. Depois de definir o resultado desejado, você pode então atualizar o gerador.

    Na prática, este processo pode ser assim:

    1. Crie um novo workspace

      Terminal window
      npx create-nx-workspace@22.5.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --ci=skip --aiAgents

    2. Execute quaisquer geradores que possam ser pré-requisitos para seu novo gerador/recurso/correção

    3. Faça commit das suas alterações (git commit)

    4. Faça as alterações desejadas e teste-as conforme necessário

    5. Use o git diff das suas alterações para informar quais mudanças devem ser feitas no Nx Plugin for AWS

    6. Execute um teste final end-to-end (vinculando seu @aws/nx-plugin) para garantir que seu gerador gera as alterações necessárias