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. Impiega TanStack Router per il routing type-safe.

Sebbene questo generatore configuri CloudScape, si tratta fondamentalmente di un generatore di progetti React. 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 CloudScape

Puoi generare un nuovo sito web CloudScape 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#cloudscape-website
5. Compila i parametri richiesti
6. Clicca su Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#cloudscape-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.

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 modificare 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 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 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. Aggiungere nuove route è semplice:

1. Avvia il server di sviluppo locale
2. Crea un nuovo file <page-name>.tsx in src/routes, dove la posizione nell’albero dei file 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 di TanStack Router.

Configurazione runtime

La configurazione dalla tua infrastruttura AWS CDK viene fornita al sito web tramite Runtime Configuration. Questo permette al sito 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 nell’infrastruttura CDK. I costrutti CDK generati da @aws/nx-plugin (come API tRPC e FastAPI) aggiungeranno automaticamente i valori appropriati a RuntimeConfig.

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

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

Codice del sito web

Nel 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 directory public per far conoscere al sito locale gli URL dei backend, la configurazione identity, ecc.

Il progetto del sito web è 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"

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

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 sito web. Richiede che tutta l’infrastruttura di supporto con cui interagisce il sito sia già distribuita, e che la configurazione runtime locale sia stata caricata.

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” già distribuite.

Target Serve Local

Il target serve-local avvia un server di sviluppo locale per il sito web (con Vite MODE impostato a serve-local), e avvia anche server locali per le 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 delle API in esecuzione locale.

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 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 config runtime.

Build

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

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

Test

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

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

Puoi eseguire i test con il target test:

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

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

Puoi usare il costrutto 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');
  }
}