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:

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

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

yarn

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

npm

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

bun

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

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

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	Nome do projeto TypeScript
directory	string	packages	Diretório pai onde a biblioteca é colocada.
subDirectory	string	-	O subdiretório onde a biblioteca é colocada. Por padrão, este é o nome da biblioteca.
preferInstallDependencies	boolean	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 Empty 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
      • 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
      • utils.ts Utility functions for the MCP server
  • generators.json Nx generator configuration (initially empty)
  • package.json Plugin package configuration
  • tsconfig.json TypeScript configuration (CommonJS for Nx compatibility)
  • project.json Nx project configuration with build and package targets

Trabalhando com Seu Nx Plugin

Adicionando Geradores

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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 --project=your-plugin --dry-run

yarn

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

npm

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

bun

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

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
   • project: your-plugin
6. Clique em Generate

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
• Arquivos de configuração de geradores e executores
• 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.

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

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

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

Publicando no NPM

Quando seu plugin estiver pronto:

cd dist/your-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:

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

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

pnpm

pnpm nx g your-plugin-name:your-generator-name --dry-run

yarn

yarn nx g your-plugin-name:your-generator-name --dry-run

npm

npx nx g your-plugin-name:your-generator-name --dry-run

bun

bunx nx g your-plugin-name:your-generator-name --dry-run

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