Guida Rapida

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

Tutorial Full-Stack

Per un tutorial più approfondito sulla costruzione di un’applicazione full-stack, consulta il Tutorial Dungeon Adventure.

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.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.

Passaggio 1: Inizializzare un Nuovo Workspace Nx

Esegui il seguente comando per creare un workspace Nx con il package manager di tua scelta:

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

Scegliere un Provider IaC

Ti verrà richiesto di scegliere il tuo provider di infrastructure as code (IaC) preferito, CDK o Terraform. Puoi saltare il prompt eseguendo il comando con --iac, ad esempio:

CDK

pnpm

pnpm create @aws/nx-workspace my-project --iac=cdk

yarn

yarn create @aws/nx-workspace my-project --iac=cdk

npm

npm create @aws/nx-workspace -- my-project --iac=cdk

bun

bun create @aws/nx-workspace my-project --iac=cdk

Terraform

pnpm

pnpm create @aws/nx-workspace my-project --iac=terraform

yarn

yarn create @aws/nx-workspace my-project --iac=terraform

npm

npm create @aws/nx-workspace -- my-project --iac=terraform

bun

bun create @aws/nx-workspace my-project --iac=terraform

Una volta completato, naviga nella directory del progetto:

cd my-project

Passaggio 2: Utilizzare i Generatori per Strutturare il Progetto

Aggiungeremo un’API tRPC, un sito web React, l’autenticazione Cognito e l’infrastruttura CDK o Terraform in questa guida rapida. 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.

Come scorciatoia, puoi utilizzare il pulsante qui sotto per copiare i comandi per strutturare l’applicazione completa.

Loading the diagram…

Costruire con l’AI

Il Nx Plugin for AWS MCP Server è già configurato nel tuo workspace, quindi puoi chiedere al tuo agente di codifica AI preferito come Kiro o Claude di costruire questi progetti per te invece di digitare i comandi CLI tu stesso.

Altrimenti, segui i passaggi seguenti per eseguire ogni generatore da solo.

Aggiungere un’API tRPC

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --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#api
5. Compila i parametri richiesti
   • name: demo-api
   • framework: trpc
   • auth: iam
6. Clicca su Generate

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

Aggiungere un Sito Web React

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --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#website
5. Compila i parametri richiesti
   • name: demo-website
6. Clicca su Generate

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

Aggiungere l’Autenticazione Cognito

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --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#website#auth
5. Compila i parametri richiesti
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Clicca su Generate

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

Connettere Frontend e Backend

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --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 - connection
5. Compila i parametri richiesti
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Clicca su Generate

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --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#infra
5. Compila i parametri richiesti
   • name: infra
6. Clicca su Generate

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

Terraform

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --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 - terraform#project
5. Compila i parametri richiesti
   • name: infra
6. Clicca su Generate

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.

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 { Stack, StackProps } from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from '@my-project/common-constructs';
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:

# Include metrics tracking for @aws/nx-plugin usage
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# 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]
}

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

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

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

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.

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.

---

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