Salta ai contenuti
@aws/nx-plugin
Blog

Sito Web CloudScape

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

Genera un sito web CloudScape

Puoi generare un nuovo sito web CloudScape in due modi:

  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
    • Clicca su Generate

    Opzioni

    Parametro Tipo Predefinito Descrizione
    name Obbligatorio string - The name of the application.
    directory string packages The directory of the new application.

    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 generale CloudScape e barra di navigazione
      • Directoryhooks
        • useAppLayout.tsx Hook per regolare l’AppLayout da componenti annidati
      • Directoryroutes
        • Directorywelcome
          • index.tsx Route (o pagina) di esempio 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 tuo sito web CloudScape

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

    Route

    Creazione di una Route/Pagina

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

    1. Esegui il server di sviluppo locale
    2. Crea un nuovo file <page-name>.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!

    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 di TanStack Router.

    Configurazione Runtime

    La configurazione dalla tua infrastruttura AWS CDK viene fornita al tuo sito web tramite Runtime Configuration. Questo permette al tuo sito web di accedere a dettagli come URL di API che non sono noti finché l’applicazione non viene distribuita.

    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 tuo costrutto CDK per il sito web distribuirà la configurazione runtime come file runtime-config.json nella root del tuo 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');
    

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

    Devi assicurarti di dichiarare il tuo sito web dopo qualsiasi costrutto che aggiunge valori 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 configurazione runtime:

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

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

      // Accedi ai valori della config runtime qui
      const apiUrl = runtimeConfig.httpApis.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 web locale gli URL di backend, la configurazione di identità, ecc.

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

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

    Se modifichi il nome del tuo stack nel src/main.ts del progetto infrastruttura, dovrai aggiornare il target load:runtime-config nel file project.json del tuo sito web con il nome dello stack da cui caricare la configurazione runtime.

    Server di sviluppo locale

    Prima di eseguire il server di sviluppo locale, assicurati di aver distribuito la tua infrastruttura e aver caricato la configurazione runtime locale.

    Puoi quindi eseguire il target serve:

    Terminal window
    pnpm nx run <my-website>:serve

    Build

    Puoi compilare il tuo sito web usando il target build. Questo utilizza Vite per creare un bundle di produzione nella directory root dist/packages/<my-website>/bundle, oltre a verificare i tipi, compilare e lintare il tuo sito web.

    Terminal window
    pnpm nx run <my-website>:build

    Test

    Testare il tuo sito web è simile a scrivere test in un normale progetto TypeScript, quindi consulta la guida ai progetti TypeScript per maggiori dettagli.

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

    Puoi eseguire i test usando il target test:

    Terminal window
    pnpm nx run <my-website>:test

    Distribuzione del sito web

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

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

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