TypeScript Nx Plugin

Gere um Nx Plugin TypeScript completo com um servidor Model Context Protocol (MCP) integrado. Este gerador cria uma base para construir geradores personalizados que podem ser usados perfeitamente por assistentes de IA para geração automatizada de código e scaffolding de projetos.

Uso

Gerar um Nx Plugin

Você pode gerar um TypeScript Nx Plugin de duas maneiras:

Execute este gerador@aws/nx-plugin:ts#nx-plugin

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

Monte seu comando4

nameObrigatório

directory

subDirectory

preferInstallDependencies

true

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

Opções

Opções do gerador4 opções

nameObrigatóriostring

Nome do projeto TypeScript

directorystringPadrão: packages

Diretório pai onde a biblioteca é colocada.

subDirectorystring

O subdiretório onde a biblioteca é colocada. Por padrão, este é o nome da biblioteca.

preferInstallDependenciesbooleanPadrão: true

Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos do Nx); instale uma vez no final.

Saída do Gerador

O gerador criará a seguinte estrutura de projeto:

• Directoryyour-plugin/

  • Directorysrc/

    • index.ts Entry point for your plugin
    • Directorymcp-server/

      • index.ts Exports your server
      • server.ts Main MCP server configuration
      • stdio.ts Entry point for your MCP server with STDIO transport
      • http.ts Entry point for your MCP server with Streamable HTTP transport
      • schema.ts Shared schemas for the MCP server’s tools
      • utils.ts Utility functions for the MCP server
      • Directoryresources/

        • GENERAL_GUIDANCE.md Guidance served by the general-guidance tool
      • Directorytools/

        • create-workspace-command.ts Tool for workspace creation guidance
        • general-guidance.ts Tool for general Nx and plugin guidance
        • list-generators.ts Tool to list available generators
        • generator-guide.ts Tool for detailed generator information
  • generators.json Nx generator configuration (initially empty)
  • package.json Plugin package configuration
  • project.json Nx project configuration with build and package targets
  • tsconfig.json TypeScript configuration, referencing the two below
  • tsconfig.lib.json TypeScript configuration for your plugin’s source
  • tsconfig.spec.json TypeScript configuration for your plugin’s tests
  • vitest.config.mts Vitest configuration for your plugin’s tests
  • README.md Documentation for your plugin, served by the generator-guide tool
  • LICENSE Written by the license generator’s sync, when configured

Trabalhando com Seu Nx Plugin

Adicionando Geradores

Depois de ter seu projeto de plugin, você pode adicionar geradores usando o gerador ts#nx-generator:

Execute este gerador@aws/nx-plugin:ts#nx-generator

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

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

Monte seu comando5

projectObrigatório

nameObrigatório

description

directory

preferInstallDependencies

true

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

Isso adicionará um novo gerador ao seu plugin.

Documentação do Gerador

Leia o guia ts#nx-generator para detalhes sobre como implementar geradores.

Certifique-se de escrever um README.md detalhado para seu gerador, pois ele é usado pela ferramenta generator-guide do MCP Server.

Targets do Projeto

O plugin gerado inclui vários targets importantes:

Target Build

Compila seu código TypeScript e prepara o plugin para uso:

pnpm

pnpm nx build your-plugin

yarn

yarn nx build your-plugin

npm

npx nx build your-plugin

bun

bunx nx build your-plugin

Target Package

Cria um pacote distribuível pronto para publicação no NPM:

pnpm

pnpm nx package your-plugin

yarn

yarn nx package your-plugin

npm

npx nx package your-plugin

bun

bunx nx package your-plugin

O target package inclui todos os recursos necessários:

• Arquivos JavaScript compilados
• Arquivos de declaração TypeScript
• Os manifestos generators.json, executors.json e migrations.json que o Nx lê de um plugin publicado
• Arquivos de documentação e licença

Integração com MCP Server

O plugin configura um servidor MCP usando o gerador ts#mcp-server.

Ferramentas

O plugin inclui um servidor MCP completo que fornece aos assistentes de IA as seguintes ferramentas:

• general-guidance: Obtenha as melhores práticas para trabalhar com Nx e seu plugin
• create-workspace-command: Aprenda como criar novos workspaces que podem usar seu plugin
• list-generators: Liste todos os geradores disponíveis em seu plugin
• generator-guide: Obtenha informações detalhadas sobre geradores específicos, incluindo schemas e uso

Configurando com Assistentes de IA

Arquivos de Configuração

A maioria dos assistentes de IA que suportam MCP usa uma abordagem de configuração similar. Você precisará criar ou atualizar um arquivo de configuração com os detalhes do seu servidor MCP:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

Resolução de Caminho

Se você receber um erro como ENOENT npx ao conectar ao seu servidor, pode ser necessário especificar o caminho completo para npx, que você pode obter executando which npx no seu terminal.

Hot Reload

Ao desenvolver seu servidor MCP, você pode desejar configurar a flag --watch para que o assistente de IA sempre veja as versões mais recentes das ferramentas/recursos:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

Atualizando Ferramentas

Se você adicionar novas ferramentas ou recursos, pode ser necessário atualizar seu servidor MCP no assistente de IA.

Configuração Específica do Assistente

Por favor, consulte a seguinte documentação para configurar MCP com Assistentes de IA específicos:

• Kiro
• Kiro CLI
• Claude Code
• Cursor
• Codex
• Cline
• Roo Code

Configuração do Workspace

Alguns Assistentes de IA, como Kiro, permitem que você especifique a configuração do servidor MCP no nível do workspace, o que é particularmente útil para definir os servidores MCP relevantes para um projeto específico.

Personalizando o MCP Server

Você pode estender o servidor MCP modificando server.ts para adicionar ferramentas ou recursos adicionais específicos ao domínio do seu plugin.

Para mais detalhes sobre como escrever MCP Servers, consulte o guia ts#mcp-server.

Publicando Seu Plugin

Preparando para Publicação

1. Atualize as Informações do Pacote: Edite o package.json do seu plugin com nome, versão, descrição e informações de repositório adequados. Também remova "private": true.

2. Construa o Pacote:

   pnpm

   pnpm nx package your-plugin

   yarn

   yarn nx package your-plugin

   npm

   npx nx package your-plugin

   bun

   bunx nx package your-plugin

   O pacote é colocado em dist/<raiz do projeto do seu plugin>/package — para um plugin gerado com --name=nx-plugin --directory=tools, isso é dist/tools/nx-plugin/package.

3. Teste Localmente: Você pode testar seu plugin localmente instalando-o em outro workspace:

   npm install /path/to/your/workspace/dist/tools/nx-plugin/package

Publicando no NPM

Quando seu plugin estiver pronto:

cd dist/tools/nx-plugin/package
npm publish

Usando Plugins Publicados

Após a publicação, outros podem instalar e usar seu plugin:

pnpm

pnpm add -w your-plugin-name

yarn

yarn add your-plugin-name

npm

npm install --legacy-peer-deps your-plugin-name

bun

bun add your-plugin-name

Em seguida, use seus geradores:

Execute este geradoryour-plugin-name:your-generator-name

CLI

pnpm

$ pnpm nx g your-plugin-name:your-generator-name

yarn

$ yarn nx g your-plugin-name:your-generator-name

npm

$ npx nx g your-plugin-name:your-generator-name

bun

$ bunx nx g your-plugin-name:your-generator-name

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 your-plugin-name - your-generator-name
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Configure Assistentes de IA com seu Plugin Publicado

O servidor MCP do seu plugin publicado pode ser configurado da seguinte forma:

{
  "mcpServers": {
    "aws-nx-mcp": {
      "command": "npx",
      "args": ["-y", "-p", "your-plugin-name", "your-plugin-name-mcp-server"]
    }
  }
}