TypeScript Nx Plugin

Genera un Nx Plugin TypeScript completo con un server Model Context Protocol (MCP) integrato. Questo generatore crea una base per costruire generatori personalizzati che possono essere utilizzati senza problemi dagli assistenti AI per la generazione automatica di codice e lo scaffolding di progetti.

Utilizzo

Generare un Nx Plugin

Puoi generare un TypeScript Nx Plugin in due modi:

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - ts#nx-plugin
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Nome del progetto TypeScript
directory	string	packages	Directory principale dove viene posizionata la libreria.
subDirectory	string	-	La sotto-directory in cui viene posizionata la libreria. Per impostazione predefinita corrisponde al nome della libreria.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore creerà la seguente struttura di progetto:

• 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

Lavorare con il Tuo Nx Plugin

Aggiungere Generatori

Una volta che hai il tuo progetto plugin, puoi aggiungere generatori utilizzando il generatore 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - ts#nx-generator
5. Compila i parametri richiesti
   • project: your-plugin
6. Clicca su Generate

Questo aggiungerà un nuovo generatore al tuo plugin.

Documentazione del Generatore

Leggi la guida ts#nx-generator per i dettagli su come implementare i generatori.

Assicurati di scrivere un README.md dettagliato per il tuo generatore, poiché questo viene utilizzato dallo strumento generator-guide del MCP Server.

Target del Progetto

Il plugin generato include diversi target importanti:

Target Build

Compila il tuo codice TypeScript e prepara il plugin per l’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 package distribuibile pronto per la pubblicazione su 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

Il target package include tutte le risorse necessarie:

• File JavaScript compilati
• File di dichiarazione TypeScript
• File di configurazione per generatori ed executor
• Documentazione e file di licenza

Integrazione MCP Server

Il plugin configura un server MCP utilizzando il generatore ts#mcp-server.

Strumenti

Il plugin include un server MCP completo che fornisce agli assistenti AI i seguenti strumenti:

• general-guidance: Ottieni le best practice per lavorare con Nx e il tuo plugin
• create-workspace-command: Scopri come creare nuovi workspace che possono utilizzare il tuo plugin
• list-generators: Elenca tutti i generatori disponibili nel tuo plugin
• generator-guide: Ottieni informazioni dettagliate su generatori specifici inclusi schemi e utilizzo

Configurazione con Assistanti AI

File di Configurazione

La maggior parte degli assistenti AI che supportano MCP utilizza un approccio di configurazione simile. Dovrai creare o aggiornare un file di configurazione con i dettagli del tuo server MCP:

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

Risoluzione del Percorso

Se ricevi un errore come ENOENT npx durante la connessione al tuo server, potrebbe essere necessario specificare il percorso completo di npx, che puoi ottenere eseguendo which npx nel tuo terminale.

Hot Reload

Durante lo sviluppo del tuo server MCP, potresti voler configurare il flag --watch in modo che l’assistente AI veda sempre le versioni più recenti di strumenti/risorse:

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

Aggiornamento degli Strumenti

Se aggiungi nuovi strumenti o risorse potrebbe essere necessario aggiornare il tuo server MCP nell’assistente AI.

Configurazione Specifica per Assistente

Si prega di fare riferimento alla seguente documentazione per configurare MCP con specifici Assistenti AI:

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

Configurazione del Workspace

Alcuni Assistenti AI, come Kiro, consentono di specificare la configurazione del server MCP a livello di workspace, il che è particolarmente utile per definire i server MCP rilevanti per un particolare progetto.

Personalizzare il MCP Server

Puoi estendere il server MCP modificando server.ts per aggiungere strumenti o risorse aggiuntive specifiche per il dominio del tuo plugin.

Per maggiori dettagli sulla scrittura di MCP Server, consulta la guida ts#mcp-server.

Pubblicare il Tuo Plugin

Preparazione per la Pubblicazione

1. Aggiorna le Informazioni del Pacchetto: Modifica il package.json del tuo plugin con nome, versione, descrizione e informazioni sul repository appropriati.

2. Costruisci il Pacchetto:

   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. Testa Localmente: Puoi testare il tuo plugin localmente installandolo in un altro workspace:

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

Pubblicazione su NPM

Una volta che il tuo plugin è pronto:

cd dist/your-plugin/package
npm publish

Utilizzare Plugin Pubblicati

Dopo la pubblicazione, altri possono installare e utilizzare il tuo 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

Quindi utilizzare i tuoi generatori:

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca your-plugin-name - your-generator-name
5. Compila i parametri richiesti
6. Clicca su Generate

Configurare Assistenti AI con il Tuo Plugin Pubblicato

Il server MCP del tuo plugin pubblicato può essere configurato come segue:

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