Salta ai contenuti

Guida di Avvio Rapido

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

Prerequisiti

Sono necessarie le seguenti dipendenze globali prima di procedere:

  • Git
  • Node >= 22 (Consigliamo di utilizzare strumenti come NVM per gestire le versioni di Node)
    • verifica eseguendo node --version
  • PNPM >= 10 (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.12 eseguendo: uv python install 3.12.0
    2. verifica con uv python list --only-installed
  • Credenziali AWS configurate per il tuo account AWS target (dove verrà distribuita l’applicazione)
  • Se utilizzi VSCode, consigliamo di installare l’Nx Console VSCode Plugin.

Step 1: Inizializzare una Nuova Workspace Nx

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

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

Al termine, accedi alla directory del progetto:

Terminal window
cd my-project

Step 2: Utilizzare i Generator per Scaffoldare 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 generator 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

  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

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

Aggiungere un Sito React

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

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

Aggiungere Autenticazione Cognito

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

Collegare Frontend e Backend

  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-backend
  6. Clicca su Generate

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

Aggiungere Infrastruttura CDK

  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.

Step 3: Definire le Risorse Cloud e Distribuire 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

Successivamente, esegui questo comando per compilare il progetto:

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

Step 4: Eseguire il Frontend Localmente

  1. Recupera il file runtime-config.json:

    Terminal window
    pnpm nx run @demo/demo-website:load:runtime-config
  2. Avvia il server locale del sito

    Terminal window
    pnpm nx run @demo/demo-website:serve

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


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