Sito Web React

Questo generatore crea un nuovo sito web React con shadcn/ui configurato di default, insieme all’infrastruttura AWS CDK o Terraform per distribuire il tuo sito web sul cloud come sito statico ospitato in S3, servito da CloudFront e protetto da WAF.

L’applicazione generata utilizza Vite come strumento di build e bundler. Utilizza TanStack Router per il routing type-safe.

UX Provider

Il uxProvider predefinito è shadcn/ui. Puoi anche selezionare Cloudscape o None (porta la tua libreria di componenti).

Utilizzo

Generare un Sito Web React

Puoi generare un nuovo Sito Web React in due modi:

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#website --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website --dry-run

npm

npx nx g @aws/nx-plugin:ts#website --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website --dry-run

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Il nome dell'applicazione.
framework	react	react	Il framework frontend da utilizzare.
directory	string	packages	La directory della nuova applicazione.
subDirectory	string	-	La sotto-directory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.
ux	none | cloudscape | shadcn	shadcn	Il provider UX preferito.
tailwind	boolean	true	Abilita TailwindCSS per lo styling utility-first.
tanstackRouter	boolean	true	Abilita Tanstack router per il routing type-safe.
infra	cloudfront-s3 | none	cloudfront-s3	Il tipo di infrastruttura con cui distribuire il tuo sito web.
iac	inherit | cdk | terraform	inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare 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.

Output del Generatore

Il generatore creerà la seguente struttura del progetto nella directory <directory>/<nome>:

• index.html Punto di ingresso HTML
• public Asset statici
• Directorysrc

  • main.tsx Punto di ingresso dell’applicazione con configurazione React
  • config.ts Configurazione dell’applicazione (es. logo)
  • Directorycomponents

    • AppLayout Componenti per il layout generale e la barra di navigazione
  • Directoryhooks

    • useAppLayout.tsx Hook per regolare l’AppLayout da componenti annidati (solo Cloudscape)
  • Directoryroutes

    • index.tsx Route di esempio (o pagina) per TanStack Router
  • styles.css Stili globali
• vite.config.mts Configurazione Vite e Vitest
• tsconfig.json Configurazione TypeScript base per sorgenti e test
• tsconfig.app.json Configurazione TypeScript per il codice sorgente
• tsconfig.spec.json Configurazione TypeScript per i test

Senza TanStack Router

Se hai scelto di non utilizzare TanStack Router, riceverai un semplice file src/app.tsx come punto di ingresso dell’applicazione invece della directory routes.

Infrastruttura

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iacProvider selezionato, creerà un progetto in packages/common che include i relativi costrutti CDK o moduli Terraform.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Construct generici riutilizzati dai construct in app

      • …
    • index.ts Punto di ingresso che esporta i construct da app
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il ts#project generator e quindi configura gli stessi target di build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Moduli generici riutilizzati dai moduli in app

      • …
  • project.json Target di build e configurazione del progetto

Progetto generato

Questo progetto è generato utilizzando il terraform#project generator e quindi configura gli stessi target di build.

Il generatore crea infrastruttura as code per distribuire il tuo sito web in base al iacProvider selezionato:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorystatic-websites

      • <nome>.ts Infrastruttura specifica per il tuo sito web
  • Directorycore

    • static-website.ts Construct generico StaticWebsite

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorystatic-websites

      • Directory<nome>

        • <nome>.tf Modulo specifico per il tuo sito web
  • Directorycore

    • Directorystatic-website

      • static-website.tf Modulo generico per sito statico

Architettura

Il sito web distribuito ha la seguente architettura:

Security Headers

La distribuzione CloudFront applica una policy di response headers che imposta Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy e una Content-Security-Policy su tutte le risposte.

Una Content-Security-Policy predefinita viene applicata. Limita script e framing per mitigare XSS e clickjacking, consentendo al contempo connessioni HTTPS e WSS in modo che il sito web possa chiamare endpoint di servizi AWS (come API Gateway, Cognito e Bedrock AgentCore) i cui URL sono noti solo al momento del deploy. Per regolare la policy (ad esempio per restringere connect-src alle tue origini specifiche), modifica il valore content_security_policy nel tuo static-website.ts generato (CDK) o static-website.tf (Terraform).

runtime-config.json viene servito con Cache-Control: no-cache in modo che i browser recuperino sempre la configurazione più recente dopo un ridistribuzione, invece di usare una copia cache obsoleta.

Implementazione del Sito Web React

La documentazione React è un buon punto di partenza per apprendere le basi dello sviluppo con React.

ux = cloudscape

Puoi consultare la documentazione Cloudscape per dettagli sui componenti disponibili e il loro utilizzo.

ux = shadcn

Puoi consultare la documentazione shadcn/ui per dettagli sui componenti disponibili e il loro utilizzo.

Route

Creazione di una Route/Pagina

Il tuo sito web include TanStack Router configurato di default. Questo semplifica l’aggiunta di nuove route:

1. Avvia il Server di Sviluppo Locale
2. Crea un nuovo file <nome-pagina>.tsx in src/routes, con la posizione nell’albero dei file che rappresenta il percorso
3. Noterai che un Route e RouteComponent vengono generati automaticamente. Puoi iniziare a costruire la tua pagina qui!

Navigazione tra Pagine

Puoi usare il componente Link o l’hook useNavigate per navigare tra le pagine:

import { Link, useNavigate } from '@tanstack/react-router';

export const MyComponent = () => {
  const navigate = useNavigate();

  const submit = async () => {
    const id = await ...
    // Usa `navigate` per reindirizzare dopo un'azione asincrona
    navigate({ to: '/products/$id', { params: { id }} });
  };

  return (
    <>
      <Link to="/products">Annulla</Link>
      <Button onClick={submit}>Invia</Button>
    </>
  )
};

Per maggiori dettagli, consulta la documentazione TanStack Router.

Configurazione Runtime

La configurazione dalla tua infrastruttura viene fornita al sito web tramite Configurazione Runtime. Questo permette al sito di accedere a dettagli come URL di API non noti fino al deployment dell’applicazione.

Infrastruttura

CDK

Il construct RuntimeConfig CDK può essere usato per aggiungere e recuperare configurazioni nella tua infrastruttura CDK. I construct CDK generati dai generatori @aws/nx-plugin (come ts#trpc-api e py#fast-api) aggiungeranno automaticamente i valori appropriati a RuntimeConfig.

Il construct CDK del tuo sito web distribuirà il namespace connection della configurazione runtime come file runtime-config.json nella root del bucket S3.

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite, MyApi } from ':my-scope/common-constructs';

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

    // Il sito web può essere dichiarato in qualsiasi punto — la config runtime è risolta in modo lazy
    new MyWebsite(this, 'MyWebsite');

    // Aggiunge automaticamente valori a RuntimeConfig
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Costrutto CDK del sito web

Con CDK, il construct del sito web può essere dichiarato in qualsiasi punto dello stack. La configurazione runtime è risolta in modo lazy al momento della sintesi, quindi tutti i valori saranno inclusi indipendentemente dall’ordine di dichiarazione.

Terraform

Con Terraform, la configurazione runtime è gestita tramite moduli runtime-config. I moduli Terraform generati da generatori @aws/nx-plugin (come ts#api e py#api) aggiungeranno automaticamente valori appropriati alla configurazione runtime.

Il modulo Terraform del tuo sito web distribuirà il namespace connection della configurazione runtime come file runtime-config.json nella root del bucket S3.

packages/infra/src/main.tf

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Aggiunge automaticamente valori alla config runtime
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Distribuisce automaticamente la config runtime in runtime-config.json
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # Garantisce che l'API sia distribuita prima per aggiungere alla config runtime
  depends_on = [module.my_api]
}

Ordine dei moduli

Devi assicurarti di dichiarare il modulo del sito web dopo qualsiasi modulo che aggiunge alla configurazione runtime e configurare gli appropriati depends_on per garantire l’ordine, altrimenti mancheranno nel file runtime-config.json.

Codice del Sito Web

Nel tuo sito web, puoi usare l’hook useRuntimeConfig per recuperare valori dalla configurazione runtime:

import { useRuntimeConfig } from '../hooks/useRuntimeConfig';

const MyComponent = () => {
  const runtimeConfig = useRuntimeConfig();

  // Accedi ai valori della config runtime qui
  const apiUrl = runtimeConfig.apis.MyApi;
};

Configurazione runtime

Per dettagli su come la configurazione runtime è memorizzata in AWS AppConfig e come i consumer lato server (funzioni Lambda, agenti) possono recuperarla, consulta la guida Configurazione Runtime.

Configurazione Runtime Locale

Quando esegui il server di sviluppo locale, avrai bisogno di un file runtime-config.json nella tua directory public per far conoscere al sito locale gli URL dei backend, configurazione identity, ecc.

Il tuo progetto website è configurato con un target load:runtime-config che puoi usare per scaricare il file runtime-config.json da un’applicazione distribuita:

pnpm

pnpm nx run <my-website>:"load:runtime-config"

yarn

yarn nx run <my-website>:"load:runtime-config"

npm

npx nx run <my-website>:"load:runtime-config"

bun

bunx nx run <my-website>:"load:runtime-config"

Nomi di stage personalizzati

CDK

Se cambi il prefisso per i nomi degli stage in src/main.ts del tuo progetto infrastruttura, dovrai aggiornare il target load:runtime-config nel file project.json del tuo sito web di conseguenza.

Inoltre, nota che il target load:runtime-config assume che un singolo stage della tua applicazione sia distribuito nell’ambiente per cui hai le credenziali AWS. Dovrai modificare il comando se distribuisci più stage nello stesso account e regione.

Terraform

Per progetti Terraform, il target load:runtime-config copia il file runtime-config.json creato dopo il più recente terraform apply locale.

Server di Sviluppo Locale

Il comando canonico per lo sviluppo locale è dev, che avvia il tuo sito web (e qualsiasi server locale per le API a cui lo hai connesso) con un solo comando:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

Il target serve è anche disponibile per quando hai bisogno di controllare quanto della tua applicazione viene eseguito localmente rispetto al puntare all’infrastruttura AWS distribuita. Per una panoramica più ampia dello sviluppo locale tra progetti connessi, incluso come dev si comporta per progetti con più componenti, consulta la guida Sviluppo Locale.

Target Serve

Il target serve avvia un server di sviluppo locale per il tuo sito web. Questo target richiede che tu abbia distribuito qualsiasi infrastruttura di supporto con cui il sito interagisce, e aver caricato la configurazione runtime locale.

Puoi eseguire questo target con il seguente comando:

pnpm

pnpm nx serve <my-website>

yarn

yarn nx serve <my-website>

npm

npx nx serve <my-website>

bun

bunx nx serve <my-website>

Questo target è utile per lavorare a modifiche del sito puntando ad API “reali” distribuite e altra infrastruttura.

Target Dev

Il target dev avvia un server di sviluppo locale per il tuo sito web (con Vite MODE impostato a local-dev), avviando anche server locali per API che hai connesso al sito tramite il generatore Connection.

Quando il server locale del sito è eseguito tramite questo target, runtime-config.json viene automaticamente sovrascritto per puntare agli URL delle API in esecuzione localmente.

Puoi eseguire questo target con il seguente comando:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

Questo target è utile quando lavori sia sul sito che sulle API e vuoi iterare rapidamente senza distribuire l’infrastruttura.

Script dev del workspace

Il package.json root del tuo workspace include uno script dev che esegue il target dev per ogni progetto che ne ha uno:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Questo avvia il server di sviluppo locale per il tuo sito web (e qualsiasi altro progetto con un target dev) in un unico comando. Per eseguire solo questo sito web, usa il suo target dev (ad es. nx dev <my-website>).

Autenticazione simulata

In questa modalità, se non è presente runtime-config.json e hai configurato l’autenticazione Cognito (tramite il generatore ts#website#auth), il login sarà saltato e le richieste ai server locali non includeranno header di autenticazione.

Per abilitare login e autenticazione per dev, distribuisci l’infrastruttura e carica la config runtime.

Comportamento di Dev

Quando esegui con dev, puoi specificare qualsiasi variabile d’ambiente richiesta dalle tue API per puntare ad altre risorse AWS distribuite, per esempio:

pnpm

DYNAMODB_TABLE_NAME=xxxxx pnpm nx dev <my-website>

yarn

DYNAMODB_TABLE_NAME=xxxxx yarn nx dev <my-website>

npm

DYNAMODB_TABLE_NAME=xxxxx npx nx dev <my-website>

bun

DYNAMODB_TABLE_NAME=xxxxx bunx nx dev <my-website>

Nota che i server API locali verranno eseguiti con le credenziali AWS che hai configurato localmente.

Build

Puoi compilare il sito web con il target build. Questo esegue i target bundle, compile, test e lint, effettuando type-checking, bundling, testing e linting del sito.

pnpm

pnpm nx build <my-website>

yarn

yarn nx build <my-website>

npm

npx nx build <my-website>

bun

bunx nx build <my-website>

Il target bundle usa Vite per creare un bundle di produzione nella directory root dist/packages/<my-website>/bundle. Questo è l’artefatto distribuibile utilizzato dall’infrastruttura del sito web. Puoi eseguirlo autonomamente:

pnpm

pnpm nx bundle <my-website>

yarn

yarn nx bundle <my-website>

npm

npx nx bundle <my-website>

bun

bunx nx bundle <my-website>

Testing

Testare il sito web è simile a scrivere test in un progetto TypeScript standard, quindi consulta la guida TypeScript project per maggiori dettagli.

Per test specifici React, React Testing Library è già installato e disponibile per scrivere test. Per dettagli sul suo utilizzo, consulta la documentazione React Testing Library.

Puoi eseguire i test con il target test:

pnpm

pnpm nx test <my-website>

yarn

yarn nx test <my-website>

npm

npx nx test <my-website>

bun

bunx nx test <my-website>

Distribuzione del Sito Web

Il generatore React website crea infrastruttura as code CDK o Terraform in base al iacProvider selezionato. Puoi usarla per distribuire il sito.

CDK

Per distribuire il sito, raccomandiamo di usare il generatore ts#infra per creare un’applicazione CDK.

Puoi usare il construct CDK generato in packages/common/constructs per distribuire il sito.

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

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

    new MyWebsite(this, 'MyWebsite');
  }
}

Questo configura:

1. Un bucket S3 per l’hosting dei file statici del sito web
2. Distribuzione CloudFront per la delivery globale dei contenuti
3. Web ACL WAF per la protezione di sicurezza
4. Origin Access Control per l’accesso sicuro a S3
5. Deployment automatico dei file del sito web e della configurazione runtime

Terraform

Per distribuire il sito, raccomandiamo di usare il generatore terraform#project per creare un progetto Terraform.

Puoi usare il modulo Terraform generato in packages/common/terraform per distribuire il sito.

packages/infra/src/main.tf

# Distribuisci il sito web
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
}

Questo configura:

1. Un bucket S3 per l’hosting dei file statici del sito web
2. Distribuzione CloudFront per la delivery globale dei contenuti
3. Web ACL WAF per la protezione di sicurezza (distribuito in us-east-1)
4. Origin Access Control per l’accesso sicuro a S3
5. Deployment automatico dei file del sito web e della configurazione runtime

Regione del provider WAF

Il provider aws.us_east_1 è necessario per risorse CloudFront e WAF, che devono essere distribuite nella regione us-east-1. Assicurati che la configurazione Terraform includa questo provider:

packages/infra/src/providers.tf

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

Connessioni

Usa il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

React to tRPCChiama un'API tRPC da un sito React

React to FastAPIChiama un'API Python FastAPI da un sito React

React to Smithy APIChiama un'API Smithy da un sito React

React to Python AgentChiama un Python Agent da un sito React

React to TypeScript AgentChiama un TypeScript Agent da un sito React

React to AG-UI AgentChiama un Agent che espone il protocollo AG-UI da un sito React tramite CopilotKit

id>