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 utilizzare il tuo strumento di coding agentico preferito per aggiungere il plugin, usando il server MCP. Prova il prompt:

Add the Nx Plugin for AWS to this project.

Prerequisiti

Richiesti

• Git
• Node >= 22 (Consigliamo di utilizzare qualcosa come NVM per gestire le versioni di node)
  • verifica eseguendo node --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

Consigliati

• 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
• AWS Credentials configurate per il tuo account AWS di destinazione sono necessarie per distribuire la tua applicazione (così come per alcuni flussi di lavoro di sviluppo locale).
• Docker o Finch >= 1.6.0 è richiesto per alcuni generatori. Per Docker, le build multi-piattaforma devono essere configurate; Finch supporta le build multi-piattaforma di default.
• Terraform >= 1.12 è richiesto se scegli di usarlo per l’infrastruttura come codice invece di CDK
  • verifica eseguendo terraform --version
• Se stai usando VSCode, consigliamo di installare il Nx Console VSCode Plugin.

Configurazione Assistente AI

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

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 utilizza ancora Nx, aggiungilo prima con nx init. Questo è un passaggio gestito da Nx stesso; il plugin si basa su un workspace Nx funzionante. Funziona su un pacchetto semplice, un workspace npm/pnpm/yarn/bun, un monorepo Turborepo o Lerna:

pnpm

pnpm dlx nx@23.1.1 init

yarn

yarn dlx nx@23.1.1 init

npm

npx nx@23.1.1 init

bun

bunx nx@23.1.1 init

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

pnpm workspaces

pnpm esegue gli script di installazione solo per i pacchetti nella lista consentita, 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. Aggiungilo alla lista consentita 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 root 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 integrare la tua build esistente in Nx in modo incrementale.

Per portare i tuoi progetti esistenti sotto Nx, hai alcune opzioni a seconda del linguaggio:

• Linguaggi con un plugin Nx ufficiale — Java (Gradle o Maven) e .NET hanno plugin dedicati che inferiscono automaticamente i task dei tuoi progetti. Aggiungi quello pertinente, ad es. nx add @nx/gradle, nx add @nx/maven o nx add @nx/dotnet.
• Linguaggi con un plugin della community — ad esempio Go (@nx-go/nx-go) o Rust (@monodon/rust). Sfoglia il Nx Plugin Registry per altri.
• Qualsiasi altro linguaggio — aggiungi un project.json a ogni progetto e definisci i suoi target per eseguire i tuoi comandi di build esistenti, in modo che nx build <project> (e nx run-many) li guidino. Vedi la guida al workspace per come sono configurati project.json e i target.

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 root con il tuo sorgente direttamente sotto, 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 generati dal plugin:

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 root che funge da manifest del workspace piuttosto che da 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 root:

   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 root — init aggiorna quello che il tuo workspace utilizza.

Aggiungere il plugin

Usa nx add, che installa il plugin a una versione compatibile con la tua installazione Nx e quindi 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 root ha type: "module" rimane ESM, qualsiasi altra cosa rimane CommonJS, e il codice generato segue di conseguenza. Non sovrascrive i file esistenti, e potresti dover apportare alcune modifiche manuali dopo questo passaggio a seconda della tua 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 di progetto TypeScript rimangano sincronizzati
• tsconfig.json una configurazione TypeScript root 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) lista consentita degli 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 devDependencies @aws/nx-plugin, @aws/nx-plugin-mcp, 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 coding supportati a meno che non sia disabilitato (anche equivalenti .cursor/, .kiro/, .gemini/, .vscode/ e .codex/). Esegue il @aws/nx-plugin-mcp del workspace stesso, quindi il server corrisponde sempre alla versione installata nel tuo workspace

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

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

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

nx build <project> non funziona più per una libreria TypeScript esistente

La prima esecuzione di ts#project configura il plugin @nx/js/typescript per inferire il target di build TypeScript come compile (il plugin riserva build per orchestrare lint, compile e test). Anche le librerie esistenti che si basano sul target build inferito vengono inferite come compile — esegui nx run <project>:compile, o usa nx run-many --target build,compile. Le librerie con un target build esplicito nel loro project.json non sono interessate.

The workspace is out of sync

I riferimenti di progetto 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 lista consentita. init aggiunge alla lista consentita 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 versioni diverse 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 root 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 la discrepanza. Allinea ogni voce nx e @nx/* nel tuo package.json root 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 root alla versione che il plugin utilizza (il generatore init installa una versione compatibile) e reinstalla.

Recursive task invocation detected

Il tuo package.json root è registrato come progetto Nx (ha una chiave "nx", che nx init aggiunge per un repo a pacchetto singolo) e contiene uno script build di nx run-many --target build. Nx quindi inferisce un target build sulla root che chiama se stesso. Sposta il tuo sorgente in packages/<your-package>/ in modo che la root 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 root; 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 contengono le impostazioni TypeScript di cui hanno bisogno nel loro tsconfig.lib.json per progetto, quindi si compilano indipendentemente dal tuo tsconfig.base.json. Questi errori si manifestano invece in un progetto preesistente 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 evitare di rompere silenziosamente i progetti che ne ereditano — risolvere queste discrepanze è 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 root: type: "module" significa ESM, qualsiasi altra cosa (inclusa l’assenza del campo type) significa CommonJS. init preserva quello che il tuo workspace utilizza, e i generatori TypeScript del plugin emettono codice corrispondente. Se in seguito vuoi cambiare, modifica il type root — ma questa è una migrazione del tuo codice esistente, non qualcosa che init fa per te.