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 nel cloud come sito web 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.

Provider UX

Il ux 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:

CLI

pnpm

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

yarn

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

npm

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

bun

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

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

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
   • framework: react
6. Clicca su Generate

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 di progetto nella directory <directory>/<name>:

• index.html HTML entry point
• public Static assets
• Directorysrc

  • main.tsx Application entry point with React setup
  • config.ts Application configuration (eg. logo)
  • Directorycomponents

    • AppLayout Components for the overall layout and navigation bar
  • Directoryhooks

    • useAppLayout.tsx Hook for adjusting the AppLayout from nested components (Cloudscape only)
  • Directoryroutes

    • index.tsx Example route (or page) for TanStack Router
  • styles.css Global styles
• vite.config.mts Vite and Vitest configuration
• tsconfig.json Base TypeScript configuration for source and tests
• tsconfig.app.json TypeScript configuration for source code
• tsconfig.spec.json TypeScript configuration for tests
• package.json Project manifest defining the project’s package name and dependencies

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 iac scelto, creerà un progetto in packages/common che include i costrutti CDK o i moduli Terraform pertinenti.

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

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Progetto Generato

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

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Progetto Generato

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

Il generatore crea infrastruttura come codice per distribuire il tuo sito web in base al tuo iac selezionato:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorystatic-websites

      • <name>.ts Infrastructure specific to your website
  • Directorycore

    • static-website.ts Generic StaticWebsite construct

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorystatic-websites

      • Directory<name>

        • <name>.tf Module specific to your website
  • Directorycore

    • Directorystatic-website

      • static-website.tf Generic static website module

Architettura

Il sito web distribuito ha la seguente architettura:

Implementare il tuo sito web

La documentazione React è un buon punto di partenza per imparare le basi della costruzione con React.

ux = cloudscape

Puoi fare riferimento alla documentazione Cloudscape per dettagli sui componenti disponibili e su come utilizzarli.

ux = shadcn

Puoi fare riferimento alla documentazione shadcn/ui per dettagli sui componenti disponibili e su come utilizzarli.

Route

Creare una route/pagina

Il tuo sito web viene fornito con TanStack Router configurato di default. Questo rende facile aggiungere nuove route:

1. Esegui il server di sviluppo locale
2. Crea un nuovo file <page-name>.tsx in src/routes, con la sua posizione nell’albero dei file che rappresenta il percorso
3. Nota che un Route e RouteComponent vengono generati automaticamente per te. Puoi iniziare a costruire la tua pagina qui!

Navigare tra le pagine

Puoi utilizzare 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 ...
    // Use `navigate` for redirecting after some asynchronous action
    navigate({ to: '/products/$id', { params: { id }} });
  };

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

Per maggiori dettagli, consulta la documentazione di TanStack Router.

Distribuire il tuo sito web

Il generatore di siti web React crea infrastruttura come codice CDK o Terraform in base al tuo iac selezionato. Puoi utilizzarla per distribuire il tuo sito web.

CDK

Per distribuire il tuo sito web, consigliamo di utilizzare il generatore ts#infra per creare un’applicazione CDK.

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

Questo configura:

1. Un bucket S3 per ospitare i file del tuo sito web statico
2. Distribuzione CloudFront per la distribuzione globale dei contenuti
3. WAF Web ACL per la protezione della sicurezza
4. Origin Access Control per l’accesso sicuro a S3
5. Distribuzione automatica dei file del sito web e della configurazione runtime

Terraform

Per distribuire il tuo sito web, consigliamo di utilizzare il generatore terraform#project per creare un progetto Terraform.

Puoi utilizzare il modulo Terraform generato per te in packages/common/terraform per distribuire il tuo sito web.

packages/infra/src/main.tf

# Deploy website
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 ospitare i file del tuo sito web statico
2. Distribuzione CloudFront per la distribuzione globale dei contenuti
3. WAF Web ACL per la protezione della sicurezza (distribuito in us-east-1)
4. Origin Access Control per l’accesso sicuro a S3
5. Distribuzione automatica dei file del sito web e della configurazione runtime

Regione del provider WAF

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

packages/infra/src/providers.tf

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

Header di sicurezza

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

Viene applicata una Content-Security-Policy predefinita. Essa limita gli script e il framing per mitigare XSS e clickjacking, consentendo al contempo connessioni HTTPS e WSS in modo che il sito web possa chiamare gli endpoint dei servizi AWS (come API Gateway, Cognito e Bedrock AgentCore) i cui URL sono noti solo al momento della distribuzione. 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 (CDK) o static-website.tf (Terraform) generato.

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

WAF

La distribuzione CloudFront è protetta da un AWS WAFv2 Web ACL di default. Il Web ACL utilizza il set di regole predefinito gestito da AWS (AWSManagedRulesCommonRuleSet e AWSManagedRulesKnownBadInputsRuleSet), fornendo protezione contro exploit web comuni inclusi OWASP Top 10.

CDK

Per disattivare, imposta enableWaf su false quando crei il tuo sito web:

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

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

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

    const website = new MyWebsite(this, 'MyWebsite', {
      enableWaf: false,
    });

    // Disabling WAF fails the checkov CKV_AWS_68 check ("CloudFront
    // Distribution should have WAF enabled"). Suppress it explicitly.
    suppressRules(
      website.cloudFrontDistribution,
      ['CKV_AWS_68'],
      'WAF is intentionally disabled for this distribution',
    );
  }
}

Sopprimere CKV_AWS_68 quando si disabilita WAF

Disabilitare WAF significa che la distribuzione CloudFront sintetizzata non ha un Web ACL associato, il che fa fallire la scansione di sicurezza checkov con CKV_AWS_68: "CloudFront Distribution should have WAF enabled" a meno che non venga soppresso come mostrato sopra.

Terraform

Per disattivare, imposta enable_waf su false:

packages/infra/src/main.tf

module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
  enable_waf = false
}

Crittografia del bucket

Il bucket del sito web, il bucket dei log della distribuzione CloudFront e il gruppo CloudWatch Logs che riceve i loro log di accesso al server sono crittografati con una chiave AWS KMS gestita dal cliente di default. Questa chiave viene creata automaticamente per te, con la rotazione delle chiavi abilitata.

CDK

Se desideri utilizzare una configurazione di crittografia diversa, passa le proprietà encryption, encryptionKey e enableKeyRotation quando crei il tuo sito web:

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

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

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

    new MyWebsite(this, 'MyWebsite', {
      encryption: BucketEncryption.S3_MANAGED,
    });
  }
}

Sopprimere CKV_AWS_158 quando si utilizza S3_MANAGED

Scegliere BucketEncryption.S3_MANAGED significa che il gruppo di log di accesso non è più crittografato con KMS, il che fa fallire la scansione di sicurezza checkov con CKV_AWS_158. Sopprimilo:

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

import { LogGroup } from 'aws-cdk-lib/aws-logs';
import { suppressRules } from '@my-scope/common-constructs';

suppressRules(
  website,
  ['CKV_AWS_158'],
  'Access log group is not KMS encrypted when encryption is S3_MANAGED',
  (c) => c instanceof LogGroup,
);

Per utilizzare la tua chiave KMS invece di una creata automaticamente, passa encryptionKey:

new MyWebsite(this, 'MyWebsite', {
  encryptionKey: myKey,
});

Le chiavi importate necessitano delle proprie autorizzazioni

Una chiave importata tramite Key.fromKeyArn deve già concedere ai principali dei servizi CloudWatch Logs, S3 e CloudFront le autorizzazioni di cui hanno bisogno nella propria policy della chiave. addToResourcePolicy è un no-op su una chiave importata, quindi questo costrutto non può concederle per te, e cdk synth non ti avviserà - il fallimento si manifesta solo al momento della distribuzione. Una chiave creata nella stessa app (new Key(this, 'WebsiteKey')) non ha questo problema, poiché CDK può aggiornare direttamente la sua policy.

enableKeyRotation (default true) si applica solo alla chiave creata automaticamente, cioè quando encryption è BucketEncryption.KMS (il default) e non viene fornita alcuna encryptionKey:

new MyWebsite(this, 'MyWebsite', {
  enableKeyRotation: false,
});

Sopprimere CKV_AWS_7 quando si disabilita la rotazione delle chiavi

Disabilitare la rotazione delle chiavi sulla chiave creata automaticamente fa fallire la scansione di sicurezza checkov con CKV_AWS_7. Sopprimilo:

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

import { Key } from 'aws-cdk-lib/aws-kms';
import { suppressRules } from '@my-scope/common-constructs';

suppressRules(
  website,
  ['CKV_AWS_7'],
  'Key rotation is managed externally',
  (c) => c instanceof Key,
);

Terraform

Se desideri utilizzare una configurazione di crittografia diversa, imposta le variabili encryption, kms_key_arn, create_kms_key e enable_key_rotation:

packages/infra/src/main.tf

module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
  encryption = "S3_MANAGED"
}

Checkov: S3_MANAGED

Scegliere S3_MANAGED fa fallire la scansione di sicurezza checkov con CKV_AWS_145 sui bucket del sito web e dei log di distribuzione. Il target test fornito non accetta un --config-file, ma checkov scopre automaticamente un .checkov.yaml nella sua directory di lavoro, quindi inseriscine uno in packages/infra/src:

packages/infra/src/.checkov.yaml

skip-check:
  - CKV_AWS_145

Per utilizzare la tua chiave KMS invece di una creata automaticamente, passa kms_key_arn e imposta create_kms_key su false:

packages/infra/src/main.tf

module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
  kms_key_arn    = aws_kms_key.website.arn
  create_kms_key = false
}

Una chiave fornita dal cliente deve già concedere ai principali dei servizi CloudWatch Logs, S3 e CloudFront le autorizzazioni di cui hanno bisogno nella propria policy della chiave.

enable_key_rotation (default true) si applica solo alla chiave creata automaticamente, cioè quando encryption è "KMS" (il default) e create_kms_key è true:

packages/infra/src/main.tf

module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
  enable_key_rotation = false
}

Checkov: rotazione delle chiavi disabilitata

Disabilitare la rotazione delle chiavi sulla chiave creata automaticamente fa fallire la scansione di sicurezza checkov con CKV_AWS_7. Aggiungilo allo stesso .checkov.yaml:

packages/infra/src/.checkov.yaml

skip-check:
  - CKV_AWS_7

Dominio personalizzato e TLS

Di default, la distribuzione utilizza il nome di dominio CloudFront predefinito (*.cloudfront.net) e il suo certificato predefinito, che non supporta l’applicazione di una versione TLS minima di 1.2. Per servire il tuo sito web dal tuo dominio, fornisci un certificato ACM (che deve risiedere in us-east-1 per l’uso con CloudFront) e i tuoi nomi di dominio. Viene quindi applicata una versione TLS minima di 1.2 per i visualizzatori:

CDK

Passa le proprietà certificate e domainNames quando crei il tuo sito web:

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

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

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

    new MyWebsite(this, 'MyWebsite', {
      domainNames: ['www.example.com'],
      certificate: Certificate.fromCertificateArn(this, 'Cert',
        'arn:aws:acm:us-east-1:123456789012:certificate/...'),
    });
  }
}

Terraform

Imposta le variabili custom_domain_names e acm_certificate_arn:

packages/infra/src/main.tf

module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
  custom_domain_names = ["www.example.com"]
  acm_certificate_arn = "arn:aws:acm:us-east-1:123456789012:certificate/..."
}

Dovrai anche creare record DNS (ad esempio in Route 53) che puntano il tuo dominio alla distribuzione CloudFront.

Configurazione runtime

La configurazione dalla tua infrastruttura viene fornita al tuo sito web tramite Configurazione runtime. Questo consente al tuo sito web di accedere a dettagli come gli URL delle API che non sono noti fino a quando la tua applicazione non viene distribuita.

Infrastruttura

CDK

Il costrutto CDK RuntimeConfig può essere utilizzato per aggiungere e recuperare la configurazione nella tua infrastruttura CDK. I costrutti CDK generati dai generatori @aws/nx-plugin (come ts#api e py#api) aggiungeranno automaticamente valori appropriati al RuntimeConfig.

Il tuo costrutto CDK del sito web distribuirà il namespace connection della configurazione runtime come file runtime-config.json nella radice del tuo 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);

    // Website can be declared at any point, since runtime config is resolved lazily
    new MyWebsite(this, 'MyWebsite');

    // Automatically adds values to the RuntimeConfig
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Costrutto CDK del sito web

Con CDK, il costrutto del sito web può essere dichiarato in qualsiasi punto del tuo stack. La configurazione runtime viene 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 viene gestita tramite i moduli runtime-config. I moduli Terraform generati dai generatori @aws/nx-plugin (come ts#api e py#api) aggiungeranno automaticamente valori appropriati alla configurazione runtime.

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

packages/infra/src/main.tf

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

# Automatically adds values to runtime config
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Automatically deploys the runtime config to runtime-config.json
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # Ensure API is deployed first to add to runtime config
  depends_on = [module.my_api]
}

Ordinamento dei moduli

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

Codice del sito web

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

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

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

  // Access values in the runtime config here
  const apiUrl = runtimeConfig.apis.MyApi;
};

Configurazione runtime

Per dettagli su come la configurazione runtime viene memorizzata in AWS AppConfig e su come i consumatori 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 affinché il tuo sito web locale conosca gli URL del backend, la configurazione dell’identità, ecc.

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

pnpm

pnpm nx load-runtime-config <my-website>

yarn

yarn nx load-runtime-config <my-website>

npm

npx nx load-runtime-config <my-website>

bun

bunx nx load-runtime-config <my-website>

Nomi di stage personalizzati

CDK

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

Inoltre, vale la pena notare che il target load-runtime-config presuppone che un singolo stage della tua applicazione sia distribuito nell’ambiente per cui hai credenziali AWS. Dovrai regolare il comando se distribuisci più stage nello stesso account e regione.

Terraform

Per i progetti Terraform, il target load-runtime-config copia la configurazione runtime aggregata dal tuo più recente terraform apply locale, da dist/packages/common/terraform/runtime-config/connection.json.

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 unico 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 è disponibile anche per quando hai bisogno di controllare quanto della tua applicazione viene eseguito localmente rispetto al puntamento all’infrastruttura AWS distribuita. Per una panoramica più ampia dello sviluppo locale tra progetti connessi, incluso come si comporta dev 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 web interagisce e che tu abbia 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 sulle modifiche del sito web puntando a API “reali” distribuite e ad altra infrastruttura.

Target Dev

Il target dev avvia un server di sviluppo locale per il tuo sito web (con Vite MODE impostato su local-dev), oltre ad avviare qualsiasi server locale per le API a cui hai connesso il tuo sito web tramite il generatore Connection.

Quando il server del tuo sito web locale viene eseguito tramite questo target, runtime-config.json viene automaticamente sovrascritto per puntare agli URL delle tue 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 stai lavorando sul tuo sito web e sulla tua API e desideri iterare rapidamente senza distribuire la tua infrastruttura.

Script dev del workspace

Il package.json radice 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, utilizza il suo target dev (ad es. nx dev <my-website>).

Autenticazione simulata

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

Per abilitare il login e l’autenticazione per dev, distribuisci la tua infrastruttura e carica la configurazione 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, ad 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 tuoi server API locali verranno eseguiti con le credenziali AWS che hai configurato localmente.

Building

Puoi compilare il tuo sito web utilizzando il target build. Questo esegue i target bundle, compile, test e lint, effettuando il controllo dei tipi, il bundling, il testing e il linting del tuo sito web.

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 utilizza Vite per creare un bundle di produzione nella directory radice dist/packages/<my-website>/bundle. Questo è l’artefatto distribuibile consumato dalla tua infrastruttura del sito web. Puoi eseguirlo da solo:

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 tuo sito web è molto simile a scrivere test in un progetto TypeScript standard, quindi fai riferimento alla guida al progetto TypeScript per maggiori dettagli.

Per i test specifici di React, React Testing Library è già installato e disponibile per scrivere test. Per maggiori dettagli sul suo utilizzo, fai riferimento alla documentazione di React Testing Library.

Puoi eseguire i tuoi test utilizzando 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>

Connessioni

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

React a tRPCChiama un'API tRPC da un sito web React

React a FastAPIChiama una FastAPI Python da un sito web React

React a Smithy APIChiama un'API Smithy da un sito web React

React a Python AgentChiama un agente Python da un sito web React

React a TypeScript AgentChiama un agente TypeScript da un sito web React

React a AG-UI AgentChiama un agente che espone il protocollo AG-UI da un sito web React tramite CopilotKit

Sito web React a AgentCore GatewayConnetti un sito web React agli agenti tramite un AgentCore Gateway