Sito Web React

Questo generatore crea un nuovo sito web React con CloudScape configurato, insieme all’infrastruttura AWS CDK 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.

Utilizzo

Generare un Sito Web React

Puoi generare un nuovo sito web React in due modi:

VSCode
CLI

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - ts#react-website
Compila i parametri richiesti
Clicca su Generate

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

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

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

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

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

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.

Output del Generatore

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

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

Il generatore creerà anche il codice dell’infrastruttura CDK per distribuire il tuo sito web nella directory packages/common/constructs:

Directorysrc
- Directoryapp
  - Directorystatic-websites
    <name>.ts Infrastruttura specifica per il tuo sito web
- Directorycore
  - static-website.ts Costrutto generico StaticWebsite

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 web CloudScape include TanStack Router configurato di default. Questo semplifica l’aggiunta di nuove route:

Avvia il Server di Sviluppo Locale
Crea un nuovo file <page-name>.tsx in src/routes, con la posizione nell’albero dei file che rappresenta il percorso
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 AWS CDK viene fornita al tuo sito web tramite Runtime Configuration. Questo permette al sito di accedere a dettagli come URL di API non noti fino al deployment.

Infrastruttura

Il costrutto CDK RuntimeConfig può essere usato per aggiungere e recuperare configurazioni nella tua infrastruttura CDK. I costrutti CDK generati da @aws/nx-plugin (come API tRPC e FastAPI) aggiungeranno automaticamente valori appropriati a RuntimeConfig.

Il costrutto CDK del tuo sito web distribuirà la runtime configuration come file runtime-config.json nella root del bucket S3.

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 runtime config in runtime-config.json
    new MyWebsite(this, 'MyWebsite');
  }
}

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

Codice del Sito Web

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

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

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

  // Accedi ai valori della runtime config 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 directory public per far conoscere al sito locale gli URL di 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 nx run <my-website>:"load:runtime-config"

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

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

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

Se modifichi il prefisso degli stage name nel src/main.ts del progetto infrastruttura, dovrai aggiornare il target load:runtime-config nel file project.json del tuo sito web.

Inoltre, 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 multiple stage nello stesso account e regione.

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 che abbia caricato la runtime configuration locale.

Puoi eseguire questo target con:

pnpm nx run <my-website>:serve

yarn nx run <my-website>:serve

npx nx run <my-website>:serve

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 sito (con Vite MODE impostato a serve-local), avviando anche eventuali server locali per API connesse tramite il generatore API Connection.

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

Puoi eseguire questo target con:

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

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

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

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

Questo target è utile quando lavori contemporaneamente su sito web e 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 verrà 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 runtime config.

Build

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

pnpm nx run <my-website>:build

yarn nx run <my-website>:build

npx nx run <my-website>:build

bunx nx run <my-website>:build

Testing

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

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

Puoi eseguire i test con il target test:

pnpm nx run <my-website>:test

yarn nx run <my-website>:test

npx nx run <my-website>:test

bunx nx run <my-website>:test

Distribuzione del Sito Web

Per distribuire il sito web, raccomandiamo di usare il Generatore Infrastruttura TypeScript per creare un’applicazione CDK.

Puoi usare il costrutto CDK generato in packages/common/constructs per distribuire il tuo sito web.

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');
  }
}