Guida Rapida

Questa guida ti accompagna attraverso le basi dell’installazione e dell’utilizzo di @aws/nx-plugin per costruire rapidamente progetti su AWS.

Prerequisiti

Le seguenti dipendenze globali sono necessarie prima di procedere:

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
  2. verifica con uv python list --only-installed

Consigliati

• PNPM >= 11 (puoi anche usare Yarn >= 4, Bun >= 1, o NPM >= 11 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.

Passaggio 1: Creare un Workspace

Crea un workspace Nx con il package manager di tua scelta e apri la directory che crea:

Crea il tuo workspace@aws/nx-workspace

pnpm

$ pnpm create @aws/nx-workspace my-project

yarn

$ yarn create @aws/nx-workspace my-project

npm

$ npm create @aws/nx-workspace -- my-project

bun

$ bun create @aws/nx-workspace my-project

Componi il tuo comando3

workspaceObbligatorio

iac

cdkterraform

containers

inferdockerfinch

cd my-project

Ti viene richiesto di scegliere il tuo provider di infrastructure as code, CDK o Terraform.

Passaggio 2: Costruire la Tua Applicazione

Costruiremo un’applicazione full-stack: un’API tRPC, un sito web React, l’autenticazione Cognito e l’infrastruttura CDK o Terraform. Chiedi a un assistente AI di strutturarla per te, oppure esegui tu stesso i generatori — entrambi i percorsi portano allo stesso workspace.

Con l’AI

1. Apri il workspace nel tuo assistente di codifica AI.

   I nuovi workspace vengono forniti con il server MCP del plugin già configurato per Kiro, Claude Code, Cursor, Gemini CLI, GitHub Copilot e OpenAI Codex, quindi il tuo assistente può cercare i generatori del plugin ed eseguirli senza alcuna configurazione.

2. Chiedi l’applicazione:

   Prompt

   Create a tRPC API called demo-api, and a React website called demo-website. Add Cognito authentication to the website, connect the website to the API, and add an infrastructure project called infra. Then instantiate the generated infrastructure components so the website and API deploy, granting authenticated users access to the API.

   Il tuo assistente scopre i generatori attraverso il server MCP e li esegue, nell’ordine richiesto dalle loro dipendenze. Rivedi le modifiche che apporta, quindi continua al Passaggio 3.

Con la CLI

Esegui i generatori che strutturano l’applicazione. Usa il pulsante qui sotto per copiarli tutti, oppure esegui ciascuno tu stesso come descritto sotto il diagramma.

CDK

Loading the diagram…

Terraform

Loading the diagram…

A seconda del tipo di progetto che stai costruendo, puoi scegliere qualsiasi combinazione di generatori per avviare rapidamente il tuo progetto. Consulta i Generatori nella barra di navigazione a sinistra per vedere l’elenco completo delle opzioni, oppure prova il graph builder per costruire il tuo workspace visivamente.

Aggiungere un’API tRPC

Esegui questo generatore@aws/nx-plugin:ts#api

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#api --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#api --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#api --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#api --no-interactive

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#api
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni di questo passaggio2

nameObbligatorio

framework

trpc

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Questo creerà l’API all’interno della cartella packages/demo-api.

Aggiungere un Sito Web React

Esegui questo generatore@aws/nx-plugin:ts#website

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website --no-interactive

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#website
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni di questo passaggio1

nameObbligatorio

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Questo crea un nuovo sito web React in packages/demo-website.

Aggiungere l’Autenticazione Cognito

Esegui questo generatore@aws/nx-plugin:ts#website#auth

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website#auth --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website#auth --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website#auth --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website#auth --no-interactive

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#website#auth
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni di questo passaggio1

projectObbligatorio

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Questo configura l’infrastruttura necessaria e il codice React per aggiungere l’autenticazione Cognito al tuo sito web.

Connettere Frontend e Backend

Esegui questo generatore@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:connection --no-interactive

npm

$ npx nx g @aws/nx-plugin:connection --no-interactive

bun

$ bunx nx g @aws/nx-plugin:connection --no-interactive

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 - connection
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni di questo passaggio2

sourceProjectObbligatorio

targetProjectObbligatorio

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Questo configura i provider necessari per garantire che il tuo sito web possa chiamare la tua API tRPC.

Aggiungere l’Infrastruttura

Aggiungi il progetto di infrastruttura in base al tuo provider IAC scelto.

CDK

Esegui questo generatore@aws/nx-plugin:ts#infra

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#infra --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#infra --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#infra --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#infra --no-interactive

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#infra
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni di questo passaggio1

nameObbligatorio

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Questo configura un’app CDK che puoi utilizzare per distribuire la tua infrastruttura su AWS.

Terraform

Esegui questo generatore@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:terraform#project --no-interactive

npm

$ npx nx g @aws/nx-plugin:terraform#project --no-interactive

bun

$ bunx nx g @aws/nx-plugin:terraform#project --no-interactive

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 - terraform#project
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni di questo passaggio1

nameObbligatorio

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Questo configura un progetto Terraform che puoi utilizzare per distribuire la tua infrastruttura su AWS.

Passaggio 3: Eseguire il Sito Web e l’API Localmente

Utilizza il seguente comando per avviare i server di sviluppo locali per il tuo sito web e le sue API connesse:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Il tuo sito web sarà disponibile all’indirizzo http://localhost:4200.

Le modifiche sia al tuo sito web che all’API si rifletteranno in tempo reale poiché sia il sito web locale che i server API si ricaricheranno automaticamente.

Provalo: chiama l'API dal tuo sito web

Passaggio 4: Definire le Risorse Cloud e Distribuire su AWS

CDK

Apri packages/infra/src/stacks/application-stack.ts e aggiungi il seguente codice:

import {
  DemoApi,
  DemoWebsite,
  UserIdentity,
} from '@my-project/common-constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'identity');
    const api = new DemoApi(this, 'api', {
      integrations: DemoApi.defaultIntegrations(this).build(),
    });
    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new DemoWebsite(this, 'website');
  }
}

Questo è tutto il CDK che dobbiamo scrivere per distribuire la nostra applicazione full-stack.

Terraform

Apri packages/infra/src/main.tf e aggiungi il seguente codice:

# Deploy user identity
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Deploy API
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Grant authenticated users access to invoke the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Policy to allow authenticated users to invoke the API"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = "execute-api:Invoke"
        Resource = "${module.demo_api.api_execution_arn}/*/*"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

# Deploy website
provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

module "demo_website" {
  source = "../../common/terraform/src/app/static-websites/demo-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  depends_on = [module.user_identity, module.demo_api]
}

# Print the website URL and user pool id when the deployment finishes
output "website_url" {
  value = module.demo_website.website_url
}

output "user_pool_id" {
  value = module.user_identity.user_pool_id
}

Questo è tutto il Terraform che dobbiamo scrivere per distribuire la nostra applicazione full-stack.

Costruire e Distribuire l’Infrastruttura

Successivamente, esegui il seguente comando per costruire il tuo progetto:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Correggere gli Errori di Lint e Formattazione

Se riscontri errori di lint o formattazione, puoi eseguire il seguente comando per correggerli automaticamente.

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Il workspace non è sincronizzato

Se la build riporta The workspace is out of sync, accetta il prompt per sincronizzare il workspace oppure esegui direttamente il seguente comando di sincronizzazione prima di riprovare la build:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Questo scrive i riferimenti del progetto TypeScript e le voci di dipendenza package.json richieste dalle tue importazioni.

Esegui il bootstrap della tua infrastruttura:

CDK

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Regioni di Bootstrap

Il bootstrap di CDK è richiesto sia per la regione AWS di distribuzione di destinazione, sia per us-east-1 per consentire la distribuzione del WebACL AWS WAF per il sito web. Se stai distribuendo altrove, esegui il bootstrap anche di us-east-1:

pnpm

pnpm nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

yarn

yarn nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

npm

npx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

bun

bunx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

Terraform

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Configurazione Una Tantum

Il bootstrap di Terraform crea un bucket S3 per memorizzare i file di stato di Terraform. Questo deve essere fatto solo una volta per ogni combinazione di account AWS/regione.

Distribuisci il tuo progetto:

CDK

pnpm

pnpm nx deploy-sandbox infra

yarn

yarn nx deploy-sandbox infra

npm

npx nx deploy-sandbox infra

bun

bunx nx deploy-sandbox infra

Terraform

pnpm

pnpm nx apply infra

yarn

yarn nx apply infra

npm

npx nx apply infra

bun

bunx nx apply infra

Plan Prima di Apply

Questo comando eseguirà prima terraform plan per mostrarti quali modifiche verranno apportate, quindi applicherà tali modifiche per distribuire la tua infrastruttura.

Passaggio 5: Testare il Sito Web con le Risorse Cloud Distribuite

1. Recupera il file runtime-config.json:

   pnpm

   pnpm nx load-runtime-config demo-website

   yarn

   yarn nx load-runtime-config demo-website

   npm

   npx nx load-runtime-config demo-website

   bun

   bunx nx load-runtime-config demo-website

2. Avvia il server del sito web locale

   pnpm

   pnpm nx serve demo-website

   yarn

   yarn nx serve demo-website

   npm

   npx nx serve demo-website

   bun

   bunx nx serve demo-website

Il tuo sito web sarà disponibile all’indirizzo http://localhost:4200 e punterà alle risorse che hai distribuito per l’API e l’autenticazione.

Per accedere, dovrai creare un utente nel pool di utenti Cognito.

Clicca qui per le istruzioni usando AWS CLI

Il tuo sito web è anche servito da CloudFront. Apri il nome di dominio della sua distribuzione (che viene stampato sul tuo terminale dopo la distribuzione) per utilizzare la versione in esecuzione interamente su AWS.

Congratulazioni! 🎉 Hai costruito e distribuito con successo un’applicazione full-stack utilizzando @aws/nx-plugin!

Passaggio 6: Pulizia

Quando hai finito, elimina le risorse che hai distribuito per evitare costi continui:

CDK

pnpm

pnpm nx destroy-sandbox infra

yarn

yarn nx destroy-sandbox infra

npm

npx nx destroy-sandbox infra

bun

bunx nx destroy-sandbox infra

Risorse Conservate

Il pool di utenti Cognito viene creato con la protezione dall’eliminazione abilitata, quindi non viene rimosso automaticamente. Eliminalo (insieme al ruolo IAM che Cognito utilizza per inviare messaggi SMS) manualmente se non ne hai più bisogno.

Terraform

pnpm

pnpm nx destroy infra

yarn

yarn nx destroy infra

npm

npx nx destroy infra

bun

bunx nx destroy infra

Risorse Conservate

Il pool di utenti Cognito viene creato con la protezione dall’eliminazione abilitata, quindi non viene rimosso automaticamente (il comando destroy segnalerà un errore). Eliminalo (insieme al ruolo IAM che Cognito utilizza per inviare messaggi SMS) manualmente se non ne hai più bisogno.

Per rimuovere le risorse di bootstrap, segui le istruzioni qui sotto:

CDK

Elimina lo stack di bootstrap in ogni regione di cui hai eseguito il bootstrap, inclusa us-east-1. Questo rimuove i ruoli di bootstrap e il repository delle immagini container:

aws cloudformation delete-stack --stack-name CDKToolkit --region <region>

Asset Bucket

Il bucket degli asset viene conservato di proposito, quindi eliminalo separatamente.

Terraform

pnpm

pnpm nx bootstrap-destroy infra

yarn

yarn nx bootstrap-destroy infra

npm

npx nx bootstrap-destroy infra

bun

bunx nx bootstrap-destroy infra

Anche il Tuo Stato Terraform Viene Eliminato

Questo svuota ed elimina il bucket S3 che contiene il tuo stato Terraform, quindi eseguilo solo una volta che hai smantellato tutta l’infrastruttura distribuita.

---

Prossimi Passi

• Dungeon Adventure Tutorial — costruisci un gioco di avventura dungeon AI full-stack, per una guida più approfondita di questa.
• Workspaces — come è strutturato il tuo workspace e la configurazione che i generatori condividono.
• Aggiungere a un Progetto Esistente — adotta il plugin nella tua codebase esistente.