Guida di Avvio Rapido

Questa guida ti illustra le basi per installare e utilizzare @aws/nx-plugin per costruire rapidamente progetti su AWS.

Consiglio

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

Prerequisiti

Le seguenti dipendenze globali sono necessarie prima di procedere:

Obbligatori

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

Consigliati

• Docker è necessario per alcuni generatori
• Terraform >= 1.12 è richiesto se scegli di usarlo per l’infrastructure as code invece di CDK
  • verifica con terraform --version
• Se usi VSCode, consigliamo di installare il Nx Console VSCode Plugin

Consiglio

Se utilizzi un assistente AI come Amazon Q Developer, Cursor, Claude Code o Cline, potresti voler installare il Plugin Nx per AWS MCP server.

Step 1: Inizializzare un nuovo workspace Nx

Esegui il seguente comando per creare un workspace Nx con il package manager preferito:

pnpm

npx create-nx-workspace@~21.4.1 my-project --pm=pnpm --preset=@aws/nx-plugin --ci=skip

yarn

npx create-nx-workspace@~21.4.1 my-project --pm=yarn --preset=@aws/nx-plugin --ci=skip

npm

npx create-nx-workspace@~21.4.1 my-project --pm=npm --preset=@aws/nx-plugin --ci=skip

bun

npx create-nx-workspace@~21.4.1 my-project --pm=bun --preset=@aws/nx-plugin --ci=skip

Al termine, accedi alla directory del progetto:

cd my-project

Step 2: Utilizzare i generatori per impostare il progetto

In questa guida rapida aggiungeremo un’API tRPC, un sito React, autenticazione Cognito e infrastruttura CDK. A seconda del tipo di progetto, puoi scegliere qualsiasi combinazione di generatori per configurare rapidamente il tuo progetto. Consulta le Guide nella barra di navigazione a sinistra per l’elenco completo delle opzioni.

Aggiungere un’API tRPC

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#trpc-api
5. Compila i parametri richiesti
   • name: demo-api
   • auth: IAM
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

Questo creerà l’API nella cartella packages/demo-api.

Aggiungere un sito React

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run

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

Aggiungere autenticazione Cognito

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#react-website#auth
5. Compila i parametri richiesti
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Clicca su Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

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

Collegare frontend e backend

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 - api-connection
5. Compila i parametri richiesti
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Clicca su Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

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

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

Aggiungere infrastruttura CDK

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

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

Step 3: Eseguire il sito web e l’API in locale

Utilizza il seguente comando per avviare i server di sviluppo locali per il sito e le API collegate:

pnpm

pnpm nx run demo-website:serve-local

yarn

yarn nx run demo-website:serve-local

npm

npx nx run demo-website:serve-local

bun

bunx nx run demo-website:serve-local

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

Le modifiche al sito e all’API si rifletteranno in tempo reale grazie al hot-reload dei server locali.

Step 4: Definire le risorse cloud e distribuirle su AWS

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

import * as cdk from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from ':my-project/common-constructs';
import { Construct } from 'constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.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 codice CDK necessario per distribuire la nostra applicazione full-stack.

Compilare e distribuire l’infrastruttura

Esegui il seguente comando per compilare il progetto:

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Consiglio

Se incontri errori di linting, puoi eseguire questo comando per correggerli automaticamente:

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

Esegui il seguente comando per distribuire il progetto:

pnpm

pnpm nx run infra:deploy my-project-sandbox/*

yarn

yarn nx run infra:deploy my-project-sandbox/*

npm

npx nx run infra:deploy my-project-sandbox/*

bun

bunx nx run infra:deploy my-project-sandbox/*

Consiglio

Assicurati che il tuo ambiente AWS sia stato configurato correttamente per CDK.

Il bootstrapping CDK è necessario sia per la regione AWS target che per us-east-1 per consentire la distribuzione della WebACL AWS WAF per il sito.

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Step 5: Testare il sito web con le risorse cloud distribuite

1. Recupera il file runtime-config.json:

   pnpm

   pnpm nx run demo-website:load:runtime-config

   yarn

   yarn nx run demo-website:load:runtime-config

   npm

   npx nx run demo-website:load:runtime-config

   bun

   bunx nx run demo-website:load:runtime-config

2. Avvia il server locale del sito

   pnpm

   pnpm nx run demo-website:serve

   yarn

   yarn nx run demo-website:serve

   npm

   npx nx run demo-website:serve

   bun

   bunx nx run demo-website:serve

Il sito sarà disponibile all’indirizzo http://localhost:4200 e punterà alle risorse distribuite per l’API e l’autenticazione.

---

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