Sito Web React

Questo generatore crea un nuovo sito web React con CloudScape configurato, 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.

Nota

Sebbene questo generatore configuri CloudScape, si tratta fondamentalmente di un generatore di progetti React, e puoi modificare il codice per passare a un sistema di design alternativo o a una libreria di componenti se lo desideri.

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	The name of the application.
directory	string	packages	The directory of the new application.
enableTailwind	boolean	true	Enable TailwindCSS for utility-first styling.
enableTanstackRouter	boolean	true	Enable Tanstack router for type-safe routing.
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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 CloudScape e la barra di navigazione
  • Directoryhooks

    • useAppLayout.tsx Hook per regolare l’AppLayout da componenti annidati
  • Directoryroutes

    • Directorywelcome

      • index.tsx Route di esempio (o pagina) per @tanstack/react-router
  • styles.css Stili globali
• vite.config.ts 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

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

Nota

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

Nota

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 CDK generico per sito statico

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 Terraform generico per sito statico

Implementazione del Sito Web React

La documentazione React è un buon punto di partenza per apprendere le basi dello sviluppo con React. Puoi consultare la documentazione CloudScape per dettagli sui componenti disponibili e il loro utilizzo.

Route

Creazione di una Route/Pagina

Il tuo sito CloudScape 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 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.

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à la 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 } from ':my-scope/common-constructs';

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

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

    // Distribuisce automaticamente la config runtime in runtime-config.json
    new MyWebsite(this, 'MyWebsite');
  }
}

Attenzione

Devi assicurarti di dichiarare il tuo sito web dopo qualsiasi construct che aggiunge a RuntimeConfig, altrimenti mancheranno nel file runtime-config.json.

Terraform

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

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

packages/infra/src/main.tf

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

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

Attenzione

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

Nota

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.

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

Puoi eseguire un server di sviluppo locale usando i target serve o serve-local.

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:

pnpm

pnpm nx run <my-website>:serve

yarn

yarn nx run <my-website>:serve

npm

npx nx run <my-website>:serve

bun

bunx nx run <my-website>:serve

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

Target Serve Local

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

Quando il server locale è eseguito con questo target, runtime-config.json viene automaticamente sovrascritto per puntare agli URL API locali.

Puoi eseguire questo target con:

pnpm

pnpm nx run <my-website>:serve-local

yarn

yarn nx run <my-website>:serve-local

npm

npx nx run <my-website>:serve-local

bun

bunx nx run <my-website>:serve-local

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

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

Per abilitare login e autenticazione in serve-local, distribuisci l’infrastruttura e carica la config runtime.

Build

Puoi compilare il sito web con il target build. Questo usa Vite per creare un bundle di produzione nella directory dist/packages/<my-website>/bundle, oltre a type-checking, compilazione e linting.

pnpm

pnpm nx run <my-website>:build

yarn

yarn nx run <my-website>:build

npm

npx nx run <my-website>:build

bun

bunx nx run <my-website>:build

Testing

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

Per test specifici React, React Testing Library è già installato e disponibile. Per dettagli, consulta la documentazione React Testing Library.

Puoi eseguire i test con:

pnpm

pnpm nx run <my-website>:test

yarn

yarn nx run <my-website>:test

npm

npx nx run <my-website>:test

bun

bunx nx run <my-website>:test

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, 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
2. Distribuzione CloudFront per la delivery globale
3. Web ACL WAF per la sicurezza
4. Origin Access Control per l’accesso sicuro a S3
5. Deployment automatico dei file e config runtime

Terraform

Per distribuire, 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
2. Distribuzione CloudFront per la delivery globale
3. Web ACL WAF per la sicurezza (distribuito in us-east-1)
4. Origin Access Control per l’accesso sicuro a S3
5. Deployment automatico dei file e config runtime

Nota

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

packages/infra/src/providers.tf

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