TypeScript Nx Plugin

Genera un Nx Plugin completo en TypeScript con un servidor Model Context Protocol (MCP) integrado. Este generador crea una base para construir generadores personalizados que pueden ser utilizados sin problemas por asistentes de IA para la generación automatizada de código y el andamiaje de proyectos.

Uso

Generar un Nx Plugin

Puedes generar un TypeScript Nx Plugin de dos maneras:

Ejecute este generador@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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#nx-plugin
5. Complete los parámetros requeridos
6. Haga clic en Generate

Construya su comando4

nameRequerido

directory

subDirectory

preferInstallDependencies

true

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Opciones

Opciones del generador4 opciones

nameRequeridostring

Nombre del proyecto TypeScript

directorystringPredeterminado: packages

Directorio padre donde se coloca la biblioteca.

subDirectorystring

El subdirectorio donde se coloca la biblioteca. Por defecto es el nombre de la biblioteca.

preferInstallDependenciesbooleanPredeterminado: true

Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesaria para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador creará la siguiente estructura de proyecto:

• Directorioyour-plugin/

  • Directoriosrc/

    • index.ts Entry point for your plugin
    • Directoriomcp-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
      • Directorioresources/

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

        • 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

Trabajar con tu Nx Plugin

Agregar Generadores

Una vez que tengas tu proyecto de plugin, puedes agregar generadores usando el generador ts#nx-generator:

Ejecute este generador@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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#nx-generator
5. Complete los parámetros requeridos
6. Haga clic en Generate

Construya su comando5

projectRequerido

nameRequerido

description

directory

preferInstallDependencies

true

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Esto agregará un nuevo generador a tu plugin.

Documentación del Generador

Lee la guía de ts#nx-generator para obtener detalles sobre cómo implementar generadores.

Asegúrate de escribir un README.md detallado para tu generador, ya que esto es utilizado por la herramienta generator-guide del servidor MCP.

Targets del Proyecto

El plugin generado incluye varios targets importantes:

Target Build

Compila tu código TypeScript y prepara el plugin para su 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

Crea un paquete distribuible listo para publicar en 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

El target package incluye todos los activos necesarios:

• Archivos JavaScript compilados
• Archivos de declaración TypeScript
• Los manifiestos generators.json, executors.json y migrations.json que Nx lee de un plugin publicado
• Archivos de documentación y licencia

Integración del Servidor MCP

El plugin configura un servidor MCP usando el generador ts#mcp-server.

Herramientas

El plugin incluye un servidor MCP completo que proporciona a los asistentes de IA las siguientes herramientas:

• general-guidance: Obtén mejores prácticas para trabajar con Nx y tu plugin
• create-workspace-command: Aprende cómo crear nuevos workspaces que puedan usar tu plugin
• list-generators: Lista todos los generadores disponibles en tu plugin
• generator-guide: Obtén información detallada sobre generadores específicos, incluyendo esquemas y uso

Configurar con Asistentes de IA

Archivos de Configuración

La mayoría de los asistentes de IA que soportan MCP utilizan un enfoque de configuración similar. Necesitarás crear o actualizar un archivo de configuración con los detalles de tu servidor MCP:

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

Resolución de Rutas

Si recibes un error como ENOENT npx al conectarte a tu servidor, es posible que necesites especificar la ruta completa a npx, la cual puedes obtener ejecutando which npx en tu terminal.

Recarga en Caliente

Mientras desarrollas tu servidor MCP, es posible que desees configurar la bandera --watch para que el asistente de IA siempre vea las últimas versiones de herramientas/recursos:

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

Actualización de Herramientas

Si agregas nuevas herramientas o recursos, es posible que necesites actualizar tu servidor MCP en el asistente de IA.

Configuración Específica del Asistente

Por favor, consulta la siguiente documentación para configurar MCP con Asistentes de IA específicos:

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

Configuración del Espacio de Trabajo

Algunos Asistentes de IA, como Kiro, te permiten especificar la configuración del servidor MCP a nivel de espacio de trabajo, lo cual es particularmente útil para definir los servidores MCP relevantes para un proyecto en particular.

Personalizar el Servidor MCP

Puedes extender el servidor MCP modificando server.ts para agregar herramientas o recursos adicionales específicos del dominio de tu plugin.

Para más detalles sobre cómo escribir servidores MCP, consulta la guía de ts#mcp-server.

Publicar tu Plugin

Preparar para la Publicación

1. Actualizar Información del Paquete: Edita el package.json de tu plugin con el nombre, versión, descripción e información del repositorio adecuados. También elimina "private": true.

2. Construir el Paquete:

   pnpm

   pnpm nx package your-plugin

   yarn

   yarn nx package your-plugin

   npm

   npx nx package your-plugin

   bun

   bunx nx package your-plugin

   El paquete se coloca en dist/<raíz del proyecto de tu plugin>/package — para un plugin generado con --name=nx-plugin --directory=tools, eso es dist/tools/nx-plugin/package.

3. Probar Localmente: Puedes probar tu plugin localmente instalándolo en otro workspace:

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

Publicar en NPM

Una vez que tu plugin esté listo:

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

Usar Plugins Publicados

Después de publicar, otros pueden instalar y usar tu 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

Luego usar tus generadores:

Ejecute este generadoryour-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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque your-plugin-name - your-generator-name
5. Complete los parámetros requeridos
6. Haga clic en Generate

Configurar Asistentes de IA con tu Plugin Publicado

El servidor MCP de tu plugin publicado se puede configurar de la siguiente manera:

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