Gerador de Gerador do Nx

Adiciona um Nx Generator a um projeto TypeScript para ajudar a automatizar tarefas repetitivas como criação de componentes ou imposição de estruturas de projeto específicas.

Utilização

Gerar um Generator

Você pode gerar um generator de duas formas:

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator

npm

npx nx g @aws/nx-plugin:ts#nx-generator

bun

bunx nx g @aws/nx-plugin:ts#nx-generator

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 --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-generator --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --dry-run

Dica

Recomendamos usar o gerador ts#nx-plugin como base para qualquer generator criado, pois ele também fornece um MCP Server que ajuda a IA a utilizar seus generators.

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	TypeScript project to add the generator to. We recommend using the ts#nx-plugin generator to create this.
name Obrigatório	string	-	Generator name
description	string	-	A description of your generator
directory	string	-	The directory within the plugin project's source folder to add the generator to (default: <name>)

Saída do Generator

O generator criará os seguintes arquivos no project especificado:

• Directorysrc/<name>/

  • schema.json Esquema para entrada do generator
  • schema.d.ts Tipos TypeScript para o esquema
  • generator.ts Implementação inicial do generator
  • generator.spec.ts Testes para o generator
  • README.md Documentação do generator
• generators.json Configuração Nx para definir seus generators
• package.json Criado ou atualizado com entrada “generators”
• tsconfig.json Atualizado para usar CommonJS

Este generator atualizará o project selecionado para usar CommonJS, pois os Nx Generators atualmente só suportam CommonJS (consulte esta issue no GitHub sobre suporte a ESM).

Generators Locais

Dica

Recomendamos gerar primeiro um projeto TypeScript dedicado para todos seus generators usando o generator ts#nx-plugin. Por exemplo:

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-plugin
5. Preencha os parâmetros obrigatórios
   • name: nx-plugin
   • directory: tools
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools

yarn

yarn nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools

npm

npx nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools

bun

bunx nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools

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

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools --dry-run

Selecione seu projeto local nx-plugin ao executar o generator ts#nx-generator, e especifique um nome, diretório opcional e descrição.

Definindo o Esquema

O arquivo schema.json define as opções que seu generator aceita. Ele segue o formato JSON Schema com extensões específicas do Nx.

Estrutura Básica

Um arquivo schema.json tem a seguinte estrutura básica:

{
  "$schema": "https://json-schema.org/schema",
  "$id": "YourGeneratorName",
  "title": "Your Generator Title",
  "description": "Description of what your generator does",
  "type": "object",
  "properties": {
    // Suas opções do generator aqui
  },
  "required": ["requiredOption1", "requiredOption2"]
}

Exemplo Simples

Aqui está um exemplo simples com algumas opções básicas:

{
  "$schema": "https://json-schema.org/schema",
  "$id": "ComponentGenerator",
  "title": "Create a Component",
  "description": "Creates a new React component",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Component name",
      "x-priority": "important"
    },
    "directory": {
      "type": "string",
      "description": "Directory where the component will be created",
      "default": "src/components"
    },
    "withTests": {
      "type": "boolean",
      "description": "Whether to generate test files",
      "default": true
    }
  },
  "required": ["name"]
}

Prompts Interativos (CLI)

Você pode personalizar os prompts exibidos ao executar seu generator via CLI adicionando a propriedade x-prompt:

"name": {
  "type": "string",
  "description": "Component name",
  "x-prompt": "What is the name of your component?"
}

Para opções booleanas, use um prompt sim/não:

"withTests": {
  "type": "boolean",
  "description": "Whether to generate test files",
  "x-prompt": "Would you like to generate test files?"
}

Seleções em Dropdown

Para opções com um conjunto fixo de escolhas, use enum para permitir seleção entre as opções:

"style": {
  "type": "string",
  "description": "The styling approach to use",
  "enum": ["css", "scss", "styled-components", "none"],
  "default": "css"
}

Dropdown de Seleção de Projeto

Um padrão comum é permitir seleção entre projetos existentes no workspace:

"project": {
  "type": "string",
  "description": "The project to add the component to",
  "x-prompt": "Which project would you like to add the component to?",
  "x-dropdown": "projects"
}

A propriedade x-dropdown: "projects" instrui o Nx a preencher o dropdown com todos os projetos do workspace.

Argumentos Posicionais

Você pode configurar opções para serem passadas como argumentos posicionais na linha de comando:

"name": {
  "type": "string",
  "description": "Component name",
  "x-priority": "important",
  "$default": {
    "$source": "argv",
    "index": 0
  }
}

Isso permite executar o generator como nx g your-generator my-component em vez de nx g your-generator --name=my-component.

Definindo Prioridades

Use a propriedade x-priority para indicar opções mais importantes:

"name": {
  "type": "string",
  "description": "Component name",
  "x-priority": "important"
}

Opções podem ter prioridades "important" ou "internal". Isso ajuda o Nx a ordenar propriedades na extensão VSCode e CLI do Nx.

Valores Padrão

Você pode fornecer valores padrão para opções:

"directory": {
  "type": "string",
  "description": "Directory where the component will be created",
  "default": "src/components"
}

Mais Informações

Para mais detalhes sobre esquemas, consulte a documentação de Opções do Nx Generator.

Tipos TypeScript com schema.d.ts

Junto com schema.json, o generator cria um arquivo schema.d.ts que fornece tipos TypeScript para as opções:

export interface YourGeneratorSchema {
  name: string;
  directory?: string;
  withTests?: boolean;
}

Esta interface é usada na implementação do generator para segurança de tipos e autocompletar:

import { YourGeneratorSchema } from './schema';

export default async function (tree: Tree, options: YourGeneratorSchema) {
  // TypeScript conhece os tipos de todas as opções
  const { name, directory = 'src/components', withTests = true } = options;
  // ...
}

Cuidado

Sempre que modificar schema.json, você deve atualizar schema.d.ts para corresponder. Isso inclui:

• Adicionar ou remover propriedades
• Alterar tipos de propriedades
• Tornar propriedades obrigatórias ou opcionais (use sufixo ? para opcionais)

A interface TypeScript deve refletir com precisão a estrutura definida no schema JSON.

Implementando um Generator

Após criar o generator como acima, você pode escrever sua implementação em generator.ts.

Um generator é uma função que modula um sistema de arquivos virtual (Tree), lendo e escrevendo arquivos para fazer as mudanças desejadas. As mudanças só são escritas no disco quando o generator termina, exceto em modo “dry-run”. Um generator vazio se parece com:

export const myGenerator = async (tree: Tree, options: MyGeneratorSchema) => {
  // Use a tree para aplicar mudanças
};

export default myGenerator;

Aqui estão algumas operações comuns em generators:

Lendo e Escrevendo Arquivos

// Ler um arquivo
const content = tree.read('path/to/file.ts', 'utf-8');

// Escrever um arquivo
tree.write('path/to/new-file.ts', 'export const hello = "world";');

// Verificar se um arquivo existe
if (tree.exists('path/to/file.ts')) {
  // Fazer algo
}

Gerando Arquivos de Templates

Você pode gerar arquivos com o utilitário generateFiles do @nx/devkit, usando templates em sintaxe EJS:

import { generateFiles, joinPathFragments } from '@nx/devkit';

// Gerar arquivos de templates
generateFiles(
  tree,
  joinPathFragments(__dirname, 'files'), // Diretório do template
  'path/to/output', // Diretório de saída
  {
    // Variáveis para substituição
    name: options.name,
    nameCamelCase: camelCase(options.name),
    nameKebabCase: kebabCase(options.name),
  },
);

Manipulação de AST (Abstract Syntax Tree) TypeScript

Use tsAstReplace do Nx Plugin for AWS para modificar ASTs TypeScript:

import { tsAstReplace } from '@aws/nx-plugin/sdk/utils/ast';
import * as ts from 'typescript';

// Exemplo: Incrementar versão
tsAstReplace(
  tree,
  'path/to/version.ts',
  'VariableDeclaration:has(Identifier[name="VERSION"]) NumericLiteral',
  (node: ts.NumericLiteral) =>
    ts.factory.createNumericLiteral(Number(node.text) + 1));

Dica

Teste seletores no TSQuery Playground.

Adicionando Dependências

import { addDependenciesToPackageJson } from '@nx/devkit';

// Adicionar dependências ao package.json
addDependenciesToPackageJson(
  tree,
  {
    'new-dependency': '^1.0.0',
  },
  {
    'new-dev-dependency': '^2.0.0',
  },
);

Nota

Para instalar dependências após a geração:

import { installPackagesTask } from '@nx/devkit';

// Retorne um callback para instalar pacotes
return () => {
  installPackagesTask(tree);
};

Formatando Arquivos Gerados

import { formatFilesInSubtree } from '@aws/nx-plugin/sdk/utils/format';

// Formatar arquivos modificados
await formatFilesInSubtree(tree, 'optional/path/to/format');

Lendo e Atualizando JSON

import { readJson, updateJson } from '@nx/devkit';

// Ler JSON
const packageJson = readJson(tree, 'package.json');

// Atualizar JSON
updateJson(tree, 'tsconfig.json', (json) => {
  json.compilerOptions = {
    ...json.compilerOptions,
    strict: true,
  };
  return json;
});

Estendendo Generators do Nx Plugin for AWS

Você pode importar e estender generators existentes:

import { tsProjectGenerator } from '@aws/nx-plugin/sdk/ts';

export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
  const callback = await tsProjectGenerator(tree, { ... });

  // Estender o generator aqui

  return callback;
};

Generators OpenAPI

Você pode usar generators para clientes TypeScript e hooks:

import { openApiTsClientGenerator } from '@aws/nx-plugin/sdk/open-api';

export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
  await openApiTsClientGenerator(tree, { ... });

  // Adicionar arquivos extras
};

Também expomos métodos para iterar sobre operações OpenAPI:

import { buildOpenApiCodeGenerationData } from '@aws/nx-plugin/sdk/open-api.js';

export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
  const data = await buildOpenApiCodeGenerationData(tree, 'path/to/spec.json');

  generateFiles(
    tree,
    joinPathFragments(__dirname, 'files'),
    'path/to/output',
    data,
  );
};

Exemplo de template EJS:

files/my-operations.ts.template

export const myOperationNames = [
<%_ allOperations.forEach((op) => { _%>
  '<%- op.name %>',
<%_ }); _%>
];

Consulte o repositório no GitHub para exemplos complexos.

Executando Seu Generator

Execute seu generator de duas formas:

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 @my-project/nx-plugin - my-generator
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

pnpm nx g @my-project/nx-plugin:my-generator

yarn

yarn nx g @my-project/nx-plugin:my-generator

npm

npx nx g @my-project/nx-plugin:my-generator

bun

bunx nx g @my-project/nx-plugin:my-generator

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

pnpm

pnpm nx g @my-project/nx-plugin:my-generator --dry-run

yarn

yarn nx g @my-project/nx-plugin:my-generator --dry-run

npm

npx nx g @my-project/nx-plugin:my-generator --dry-run

bun

bunx nx g @my-project/nx-plugin:my-generator --dry-run

Nota

Se o generator não aparecer na UI do VSCode, atualize o workspace Nx com:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Testando Seu Generator

Testes unitários seguem este padrão:

import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
import { yourGenerator } from './generator';

describe('your generator', () => {
  let tree;

  beforeEach(() => {
    tree = createTreeWithEmptyWorkspace();
    tree.write('project.json', JSON.stringify({ name: 'test-project' }));
  });

  it('should generate files', async () => {
    await yourGenerator(tree, { name: 'test' });
    expect(tree.exists('src/test/file.ts')).toBeTruthy();
  });
});

Pontos-chave para testes:

• Use createTreeWithEmptyWorkspace() para sistema de arquivos virtual
• Teste criação e atualização de arquivos
• Use snapshots para conteúdo complexo
• Teste condições de erro

Contribuindo com Generators para @aws/nx-plugin

Use ts#nx-generator para criar generators dentro de @aws/nx-plugin. No nosso repositório, ele gera:

• Directorypackages/nx-plugin/src/<name>/

  • schema.json
  • schema.d.ts
  • generator.ts
  • generator.spec.ts
• Directorydocs/src/content/docs/guides/

  • <name>.mdx
• packages/nx-plugin/generators.json Atualizado

Dica

Para um guia detalhado sobre contribuição, consulte o tutorial aqui.