Aggiungere a un Progetto Esistente

Non tutti i progetti iniziano con pnpm create @aws/nx-workspace. Se hai già un workspace Nx — o un monorepo a cui puoi aggiungere Nx — puoi adottare @aws/nx-plugin in modo incrementale senza ricreare il tuo progetto.

Consiglio

Puoi usare lo strumento di codifica agente di tua scelta per aggiungere il plugin per te, utilizzando il server MCP. Prova il prompt:

Add the Nx Plugin for AWS to this project.

Prerequisiti

Obbligatori

• Git
• Node >= 22 (Consigliamo di utilizzare strumenti come NVM per gestire le versioni di Node)
  • verifica eseguendo node --version
• PNPM >= 11 (puoi anche usare Yarn >= 4, Bun >= 1 o NPM >= 10 se preferisci)
  • verifica eseguendo pnpm --version, yarn --version, bun --version o npm --version
• UV >= 0.5.29
  1. installa Python 3.14 eseguendo: uv python install 3.14.0
  2. verifica con uv python list --only-installed
• Credenziali AWS configurate per il tuo account AWS di destinazione (dove verrà distribuita la tua applicazione)

Consigliati

• Docker è necessario per alcuni generatori. Le build multi-piattaforma devono essere configurate.
• Terraform >= 1.12 è richiesto se scegli di utilizzarlo per l’infrastructure as code invece di CDK
  • verifica eseguendo terraform --version
• Se utilizzi VSCode, consigliamo di installare il Nx Console VSCode Plugin.

Configurazione dell’assistente IA

Se utilizzi un Assistente AI come Kiro, Kiro CLI, Cursor, Claude Code o Cline, potresti voler installare il Plugin Nx per AWS MCP server.

Prima di iniziare

Salva e committa prima tutto il lavoro in corso, in modo che le modifiche apportate a ogni passaggio possano essere riviste — e ripristinate — in qualsiasi momento.

Aggiungere Nx a un progetto non-Nx

Se il tuo progetto non usa ancora Nx, aggiungilo prima con nx init. Questo è un passaggio di competenza di Nx stesso; il plugin si basa su un workspace Nx funzionante. Funziona su un pacchetto semplice, un workspace npm/pnpm/yarn/bun, un Turborepo o un monorepo Lerna:

pnpm

pnpm dlx nx@23.0.2 init

yarn

yarn dlx nx@23.0.2 init

npm

npx nx@23.0.2 init

bun

bunx nx@23.0.2 init

Segui i prompt per aggiungere Nx al tuo workspace. Per maggiori dettagli consulta la Documentazione Nx.

pnpm workspaces

pnpm esegue solo gli script di installazione per i pacchetti nella allow-list, e nx ha bisogno del suo script di installazione — senza di esso, l’installazione eseguita da nx init può fallire, lasciando un placeholder set this to true or false in pnpm-workspace.yaml. Inseriscilo nella allow-list prima di eseguire nx init:

pnpm-workspace.yaml

allowBuilds:
  - nx

Progetti non-Node (Python, Go, Java, Rust, …)

Nx e il plugin sono distribuiti come pacchetti npm, quindi un progetto senza strumenti Node.js ha bisogno di un package.json radice minimo prima che nx init possa fare qualcosa di utile:

package.json

{
  "name": "my-project",
  "private": true,
  "type": "module"
}

Crea quel file, quindi esegui nx init e aggiungi il plugin come al solito. I tuoi strumenti di linguaggio esistenti rimangono intatti — i progetti Nx generati dal plugin (inclusi i progetti Python) vivono accanto al tuo codice esistente, e puoi collegare la tua build esistente in Nx in modo incrementale.

Progetti a pacchetto singolo

Il plugin è progettato per monorepo — genera ogni progetto nella propria directory sotto packages/. Se stai partendo da un progetto a pacchetto singolo (un package.json alla radice con il tuo sorgente direttamente sotto di esso, nessun workspace), sposta il tuo pacchetto esistente in packages/ prima di adottare il plugin in modo che il tuo progetto si trovi accanto a quelli che il plugin genera:

1. Crea una directory packages/<your-package>/ e sposta il tuo sorgente, package.json e tsconfig.json al suo interno.

2. Crea un nuovo package.json radice che agisce come manifest del workspace piuttosto che un progetto stesso:

   package.json

   {
     "name": "<your-workspace>",
     "private": true,
     "type": "module"
   }

3. Dichiara il workspace in modo che il tuo package manager scopra i progetti sotto packages/. Per pnpm, aggiungi un pnpm-workspace.yaml:

   pnpm-workspace.yaml

   packages:
     - packages/*

   Per npm/yarn/bun, aggiungi invece un campo workspaces al package.json radice:

   package.json

   {
     "workspaces": ["packages/*"]
   }

4. Esegui nx init (se non l’hai fatto), quindi aggiungi il plugin.

Package manager

I progetti del plugin sono generati sotto una directory packages/. pnpm legge i glob del workspace da pnpm-workspace.yaml; altri package manager leggono il campo workspaces del package.json radice — init aggiorna quello che usa il tuo workspace.

Aggiungere il plugin

Usa nx add, che installa il plugin in una versione compatibile con la tua installazione di Nx e poi esegue il suo generatore init per configurare il tuo workspace:

pnpm

pnpm nx add @aws/nx-plugin

yarn

yarn nx add @aws/nx-plugin

npm

npx nx add @aws/nx-plugin

bun

bunx nx add @aws/nx-plugin

Una volta completato, il tuo workspace è pronto — scegli i generatori di cui hai bisogno e inizia a generare progetti.

Cosa configura questo generatore

L’aggiunta del plugin apporta le modifiche deterministiche di cui un workspace ha bisogno per eseguire i generatori del plugin. Preserva il formato del modulo del tuo workspace: un workspace il cui package.json radice ha type: "module" rimane ESM, qualsiasi altra cosa rimane CommonJS, e il codice generato segue di conseguenza. Non sovrascrive i file esistenti, e potrebbe essere necessario apportare alcune modifiche manuali dopo questo passaggio a seconda della configurazione esistente.

Crea o aggiorna i seguenti file:

• aws-nx-plugin.config.mts registra il tuo provider IaC scelto (CDK o Terraform) e il motore container; i generatori leggono iac.provider da qui
• nx.json registra i generatori di sincronizzazione (@nx/js:typescript-sync e @aws/nx-plugin:ts#sync) sul target compile in modo che i riferimenti ai progetti TypeScript rimangano sincronizzati
• tsconfig.json una configurazione TypeScript radice che fa riferimento ai progetti del tuo workspace, che la sincronizzazione TypeScript di Nx mantiene aggiornata
• tsconfig.base.json le opzioni del compilatore condivise che i progetti TypeScript del plugin estendono (vedi sotto per cosa contiene)
• pnpm-workspace.yaml (solo pnpm) inserisce nella allow-list gli script di build di cui le dipendenze del plugin hanno bisogno (@swc/core, esbuild, nx, sharp)
• package.json script di convenienza per attività comuni, più le dev dependencies nx, @nx/js, @nx/workspace, typescript e Biome
• biome.json configurazione predefinita del formatter e linter Biome
• .mcp.json configura il server MCP per gli agenti di codifica supportati a meno che non sia disabilitato (anche gli equivalenti .cursor/, .kiro/, .gemini/, .vscode/ e .codex/)

La configurazione del server MCP può essere disabilitata con --mcp=false.

Clicca qui per vedere le opzioni del compilatore che contiene un tsconfig.base.json creato.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
iac	cdk | terraform	cdk	Il provider IaC preferito.
mcp	boolean	true	Se configurare il plugin Nx per il server AWS MCP da utilizzare con gli agenti di codifica.
containers	infer | docker | finch	infer	Il motore di container da utilizzare per build/push/login. 'infer' seleziona docker se installato, altrimenti finch (con fallback a docker quando nessuno dei due è installato).
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per differire 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.

Risoluzione dei problemi

The workspace is out of sync

I riferimenti ai progetti TypeScript necessitano di sincronizzazione. init registra i generatori di sincronizzazione; esegui:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

ERR_PNPM_IGNORED_BUILDS durante l’installazione

pnpm salta gli script di installazione per i pacchetti che non sono nella allow-list. init inserisce nella allow-list quelli di cui gli strumenti del plugin hanno bisogno (@swc/core, esbuild, nx, sharp) in pnpm-workspace.yaml, ma il blocco può attivarsi durante nx add @aws/nx-plugin stesso — prima che init sia stato eseguito. Esegui pnpm approve-builds e approva i pacchetti elencati (o aggiungili sotto allowBuilds:), quindi riesegui l’installazione.

nx sync si blocca, o plugin worker ... exited before the connection was established

Se due diverse versioni di nx sono presenti nello stesso albero node_modules (esegui npm ls nx per confermare), il loro IPC plugin-worker va in deadlock. Il generatore init fissa la devDependency nx radice alla versione che i pacchetti @nx/* del plugin stesso risolvono, ma un’installazione successiva di un altro pacchetto @nx/* a una versione patch diversa può reintrodurre il disallineamento. Allinea ogni voce nx e @nx/* nel tuo package.json radice a una singola versione e reinstalla.

ts.readConfigFile is not a function

Il tuo workspace ha TypeScript 7 installato, che Nx non supporta ancora — i plugin di Nx si basano sull’API del compilatore in-process di TypeScript, che TypeScript 7 non fornisce più. Fissa typescript nel tuo package.json radice alla versione che usa il plugin (il generatore init installa una versione compatibile) e reinstalla.

Recursive task invocation detected

Il tuo package.json radice è registrato come progetto Nx (ha una chiave "nx", che nx init aggiunge per un repo a pacchetto singolo) e porta uno script build di nx run-many --target build. Nx quindi deduce un target build sulla radice che chiama se stesso. Sposta il tuo sorgente in packages/<your-package>/ in modo che la radice diventi un manifest del workspace piuttosto che un progetto — vedi Progetti a pacchetto singolo. (I preset standalone di Nx stesso evitano questo impostando "nx": { "includedScripts": [] } sul pacchetto radice; puoi fare lo stesso come alternativa più rapida.)

Errori TypeScript nei tuoi progetti esistenti dopo aver aggiunto il plugin (TS6059, TS7016, TS5011, NG4006)

I progetti generati dal plugin stesso portano le impostazioni TypeScript di cui hanno bisogno nel loro tsconfig.lib.json per progetto, quindi compilano indipendentemente dal tuo tsconfig.base.json. Questi errori compaiono invece in un progetto preesistente tuo che eredita un tsconfig.base.json creato da init (con composite/emitDeclarationOnly/nodenext) ma non è compatibile con quelle impostazioni — ad esempio, il compilatore Angular rifiuta emitDeclarationOnly (NG4006), o un progetto che imposta outDir senza un rootDir ora ne ha bisogno di uno (TS5011). Aggiungi override tsconfig per progetto ridichiarando le opzioni in conflitto per quei progetti (ad es. "rootDir": "src"), o punta i progetti del plugin e i tuoi progetti a configurazioni base separate.

init non riscrive mai un tsconfig.base.json esistente, proprio per non poter rompere silenziosamente i progetti che ne ereditano — risolvere questi disallineamenti è una decisione che solo tu puoi prendere per la tua codebase.

ESM e CommonJS

Il formato del modulo è a livello di workspace, letto dal campo type del package.json radice: type: "module" significa ESM, qualsiasi altra cosa (inclusa l’assenza del campo type) significa CommonJS. init preserva quello che usa il tuo workspace, e i generatori TypeScript del plugin emettono codice corrispondente. Se in seguito vuoi cambiare, modifica il type radice — ma quella è una migrazione del tuo codice esistente, non qualcosa che init fa per te.

eparate.

init non riscrive mai un tsconfig.base.json esistente, proprio per non poter rompere silenziosamente i progetti che ne ereditano — risolvere questi disallineamenti è una decisione che solo tu puoi prendere per la tua codebase.

ESM e CommonJS

Il formato del modulo è a livello di workspace, letto dal campo type del package.json radice: type: "module" significa ESM, qualsiasi altra cosa (inclusa l’assenza del campo type) significa CommonJS. init preserva quello che usa il tuo workspace, e i generatori TypeScript del plugin emettono codice corrispondente. Se in seguito vuoi cambiare, modifica il type radice — ma quella è una migrazione del tuo codice esistente, non qualcosa che init fa per te.