Contribua com um Gerador

Aprendendo por exemplos

Este tutorial orienta você através da contribuição de um gerador para o Nx Plugin for AWS com um exemplo prático. Ele também pode servir como uma referência útil para formas de pensar e testar geradores. Você pode pular para a seção de orientação geral para algumas dicas importantes para trabalhar com geradores.

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

Primeiro, vamos clonar o plugin:

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

Em seguida, instalar e construir:

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

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:

VSCode

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

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

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.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';
}

Sistema de arquivos virtual

Observe que o gerador recebe uma Tree como entrada, além das opções definidas no schema. A Tree é essencialmente um sistema de arquivos virtual que podemos ler e escrever para criar/atualizar arquivos. Não modificamos o sistema de arquivos diretamente para evitar alterações quando usuários executam o gerador em modo “dry-run”.

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

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

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

Substituições de template

O generateFiles substitui __<variável>__ em nomes de arquivos/diretórios e remove .template. O conteúdo usa sintaxe EJS com <% ... %>.

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;

Formatação de arquivos

formatFilesInSubtree formata os arquivos gerados de acordo com as configurações Prettier do usuário.

Adicionar o Procedimento ao Router

Em seguida, queremos que o gerador conecte o novo procedimento ao router. Isso significa ler e atualizar o código-fonte do usuário!

Usamos GritQL para buscar e transformar código-fonte de forma declarativa. O helper addDestructuredImport adiciona imports nomeados, e applyGritQL aplica um padrão GritQL para adicionar o procedimento ao objeto literal 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 { addDestructuredImport, applyGritQL } from '../../utils/ast';

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');

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

  await applyGritQL(
    tree,
    routerPath,
    `\`router({ $props })\` => \`router({ $props, ${procedureNameCamelCase} })\` where { $props <: not contains \`${procedureNameCamelCase}\` }`,
  );

  await formatFilesInSubtree(tree);
};

export default trpcProcedureGenerator;

Padrões GritQL

No trecho de código acima, applyGritQL usa um padrão GritQL para encontrar a chamada router({ ... }) e adicionar o novo procedimento ao seu objeto literal. A cláusula where garante idempotência — se o procedimento já estiver presente, nenhuma alteração é feita.

Você pode experimentar padrões GritQL no Playground GritQL, ou instalar o CLI GritQL para testar padrões localmente:

npm install -g @getgrit/cli
grit apply '`router({ $props })` => `router({ $props, myProcedure })`' --dry-run

Agora que implementamos o gerador, vamos compilá-lo para garantir que esteja disponível para testarmos em nosso projeto:

pnpm nx compile @aws/nx-plugin

Testar o Gerador

Para testar o gerador, vamos vincular nosso Nx Plugin for AWS local a uma base de código existente.

Criar um Projeto de Teste com uma API tRPC

Usando seu próprio projeto

Se você completou o tutorial da aventura na masmorra, ou já tem outro workspace Nx existente que usa uma API tRPC, você pode pular esta etapa.

Em um diretório separado, crie um novo workspace de teste:

pnpm

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

yarn

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

npm

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

bun

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

Em seguida, vamos gerar uma API tRPC para adicionar o procedimento:

VSCode

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

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Em sua base de código, vamos vincular nosso @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

Caminho do plugin compilado

Observe acima que vinculamos ao plugin compilado em dist/packages/nx-plugin em vez do código-fonte.

Executar o novo Gerador

Vamos testar o novo gerador:

VSCode

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
6. Clique em 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Gerador não aparece

Se você não vir o novo gerador na lista no VSCode, pode ser necessário atualizar o workspace Nx:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Se bem-sucedido, devemos ter gerado um novo procedimento e adicionado o procedimento ao nosso router em router.ts.

Exercícios

Se você chegou até aqui e ainda tem algum tempo para experimentar com geradores Nx, aqui estão algumas sugestões de recursos para adicionar ao gerador de procedimentos:

1. Operações Aninhadas

Tente atualizar o gerador para suportar routers aninhados:

• Aceitando notação com pontos para a entrada procedure (ex: games.query)
• Gerando um procedimento com um nome baseado na notação invertida (ex: queryGames)
• Adicionando o router aninhado apropriado (ou atualizando-o se já existir!)

2. Validação

Nosso gerador deve se defender contra possíveis problemas, como um usuário selecionando um project que não é uma API tRPC. Dê uma olhada no gerador connection para um exemplo disso.

3. Testes Unitários

Escreva alguns testes unitários para o gerador. Eles são bastante diretos de implementar, e a maioria segue o fluxo geral:

1. Criar um workspace tree vazio usando createTreeUsingTsSolutionSetup()
2. Adicionar quaisquer arquivos que já devem existir na tree (ex: project.json e src/router.ts para um backend tRPC)
3. Executar o gerador em teste
4. Validar que as alterações esperadas foram feitas na tree

4. Testes End to End

Atualmente, temos um único “smoke test” que executa todos os geradores e garante que a build seja bem-sucedida. Isso deve ser atualizado para incluir o novo gerador.

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

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

   pnpm

   npx create-nx-workspace@22.6.1 my-project --pm=pnpm --preset=@aws/nx-plugin --ci=skip --analytics=false --aiAgents

   yarn

   npx create-nx-workspace@22.6.1 my-project --pm=yarn --preset=@aws/nx-plugin --ci=skip --analytics=false --aiAgents

   npm

   npx create-nx-workspace@22.6.1 my-project --pm=npm --preset=@aws/nx-plugin --ci=skip --analytics=false --aiAgents

   bun

   npx create-nx-workspace@22.6.1 my-project --pm=bun --preset=@aws/nx-plugin --ci=skip --analytics=false --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