Site Web React

Ce générateur crée un nouveau site React configuré avec shadcn/ui par défaut, ainsi que l’infrastructure AWS CDK ou Terraform pour déployer votre site web dans le cloud en tant que site statique hébergé dans S3, servi par CloudFront et protégé par WAF.

L’application générée utilise Vite comme outil de build et bundler. Elle utilise TanStack Router pour le routage type-safe.

Fournisseur UX

Le uxProvider par défaut est shadcn/ui. Vous pouvez également sélectionner Cloudscape ou None (apportez votre propre bibliothèque de composants).

Utilisation

Générer un site React

Vous pouvez générer un nouveau site React de deux manières :

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#website
5. Remplissez les paramètres requis
6. Cliquez sur Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

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

yarn

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

npm

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

bun

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

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	Le nom de l'application.
framework	react	react	Le framework frontend à utiliser.
directory	string	packages	Le répertoire de la nouvelle application.
subDirectory	string	-	Le sous-répertoire dans lequel le projet est placé. Par défaut, il s'agit du nom du projet.
ux	none | cloudscape | shadcn	shadcn	Le fournisseur UX préféré.
tailwind	boolean	true	Activer TailwindCSS pour un style utilitaire.
tanstackRouter	boolean	true	Activer le routeur Tanstack pour un routage type-safe.
infra	cloudfront-s3 | none	cloudfront-s3	Le type d'infrastructure pour déployer votre site web.
iac	inherit | cdk | terraform	inherit	Le fournisseur IaC préféré. Par défaut, il est hérité de votre sélection initiale.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir sur false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur créera la structure de projet suivante dans le répertoire <directory>/<name> :

• index.html Point d’entrée HTML
• public Assets statiques
• Répertoiresrc

  • main.tsx Point d’entrée de l’application avec la configuration React
  • config.ts Configuration de l’application (ex: logo)
  • Répertoirecomponents

    • AppLayout Composants pour le layout et la barre de navigation
  • Répertoirehooks

    • useAppLayout.tsx Hook pour ajuster l’AppLayout depuis des composants imbriqués (Cloudscape uniquement)
  • Répertoireroutes

    • index.tsx Exemple de route (ou page) pour TanStack Router
  • styles.css Styles globaux
• vite.config.mts Configuration Vite et Vitest
• tsconfig.json Configuration TypeScript de base pour le code et les tests
• tsconfig.app.json Configuration TypeScript pour le code source
• tsconfig.spec.json Configuration TypeScript pour les tests

Sans TanStack Router

Si vous avez choisi de ne pas utiliser TanStack Router, un simple fichier src/app.tsx vous sera fourni comme point d’entrée de l’application au lieu du répertoire routes.

Infrastructure

Ce générateur fournit de l’infrastructure as code basée sur votre iacProvider choisi. Il créera un projet dans packages/common qui inclut les constructions CDK ou modules Terraform pertinents.

Le projet commun d’infrastructure as code est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructions pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructions génériques réutilisées par celles dans app

      • …
    • index.ts Point d’entrée exportant les constructions depuis app
  • project.json Cibles de build et configuration du projet

Projet généré

Ce projet est généré avec le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Modules Terraform pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Modules génériques réutilisés par ceux dans app

      • …
  • project.json Cibles de build et configuration du projet

Projet généré

Ce projet est généré avec le générateur terraform#project et configure donc les mêmes cibles de build.

Le générateur crée une infrastructure as code pour déployer votre site web en fonction du iacProvider sélectionné :

CDK

• Répertoirepackages/common/constructs/src

  • Répertoireapp

    • Répertoirestatic-websites

      • <name>.ts Infrastructure spécifique à votre site
  • Répertoirecore

    • static-website.ts Construct générique StaticWebsite

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoirestatic-websites

      • Répertoire<name>

        • <name>.tf Module spécifique à votre site
  • Répertoirecore

    • Répertoirestatic-website

      • static-website.tf Module générique de site statique

Architecture

Le site web déployé a l’architecture suivante :

En-têtes de sécurité

La distribution CloudFront applique une politique d’en-têtes de réponse qui définit Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy et une Content-Security-Policy sur toutes les réponses.

Une Content-Security-Policy par défaut est appliquée. Elle restreint les scripts et le framing pour atténuer les attaques XSS et de clickjacking, tout en permettant les connexions HTTPS et WSS afin que le site puisse appeler les endpoints de services AWS (tels que API Gateway, Cognito et Bedrock AgentCore) dont les URLs ne sont connues qu’au moment du déploiement. Pour ajuster la politique (par exemple pour restreindre connect-src à vos origines spécifiques), modifiez la valeur content_security_policy dans votre fichier généré static-website.ts (CDK) ou static-website.tf (Terraform).

runtime-config.json est servi avec Cache-Control: no-cache afin que les navigateurs récupèrent toujours la dernière configuration après un redéploiement, plutôt que d’utiliser une copie en cache obsolète.

Implémentation de votre site React

La documentation React est un bon point de départ pour apprendre les bases du développement avec React.

ux = cloudscape

Vous pouvez consulter la documentation Cloudscape pour les détails sur les composants disponibles et leur utilisation.

ux = shadcn

Vous pouvez consulter la documentation shadcn/ui pour les détails sur les composants disponibles et leur utilisation.

Routes

Création d’une route/page

Votre site est configuré avec TanStack Router par défaut. Cela facilite l’ajout de nouvelles routes :

1. Lancer le serveur de développement local
2. Créer un nouveau fichier <page-name>.tsx dans src/routes, où la position dans l’arborescence représente le chemin
3. Une Route et un RouteComponent sont générés automatiquement. Vous pouvez commencer à développer votre page ici !

Navigation entre pages

Vous pouvez utiliser le composant Link ou le hook useNavigate pour naviguer entre les pages :

import { Link, useNavigate } from '@tanstack/react-router';

export const MyComponent = () => {
  const navigate = useNavigate();

  const submit = async () => {
    const id = await ...
    // Utiliser `navigate` pour rediriger après une action asynchrone
    navigate({ to: '/products/$id', { params: { id }} });
  };

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

Pour plus de détails, consultez la documentation TanStack Router.

Configuration runtime

La configuration de votre infrastructure est fournie à votre site via la Configuration Runtime. Cela permet à votre site d’accéder à des détails comme les URLs d’API qui ne sont connus qu’au moment du déploiement.

Infrastructure

CDK

Le construct CDK RuntimeConfig peut être utilisé pour ajouter et récupérer la configuration dans votre infrastructure CDK. Les constructs CDK générés par les générateurs @aws/nx-plugin (comme ts#trpc-api et py#fast-api) ajoutent automatiquement les valeurs appropriées au RuntimeConfig.

Votre construct CDK de site web déploie le namespace connection de la configuration runtime dans un fichier runtime-config.json à la racine de votre 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);

    // Le site peut être déclaré à tout moment — la config runtime est résolue de manière lazy
    new MyWebsite(this, 'MyWebsite');

    // Ajoute automatiquement des valeurs au RuntimeConfig
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Construct CDK de site web

Avec CDK, le construct de site web peut être déclaré à tout moment dans votre stack. La configuration runtime est résolue de manière lazy au moment de la synthèse, donc toutes les valeurs seront incluses quel que soit l’ordre de déclaration.

Terraform

Avec Terraform, la configuration runtime est gérée via les modules runtime-config. Les modules Terraform générés par les générateurs @aws/nx-plugin (comme ts#api et py#api) ajoutent automatiquement les valeurs appropriées à la configuration runtime.

Votre module Terraform de site web déploie le namespace connection de la configuration runtime dans un fichier runtime-config.json à la racine de votre bucket S3.

packages/infra/src/main.tf

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

# Ajoute automatiquement des valeurs à la config runtime
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Déploie automatiquement la config runtime dans runtime-config.json
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # S'assure que l'API est déployée en premier pour ajouter à la config runtime
  depends_on = [module.my_api]
}

Ordre des modules

Vous devez vous assurer de déclarer votre module de site web après tout module qui ajoute à la configuration runtime et configurer les depends_on appropriés pour garantir l’ordre, sans quoi ils seront absents du fichier runtime-config.json.

Code du site

Dans votre site, vous pouvez utiliser le hook useRuntimeConfig pour récupérer les valeurs de la configuration runtime :

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

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

  // Accéder aux valeurs de la config runtime ici
  const apiUrl = runtimeConfig.apis.MyApi;
};

Configuration d’exécution

Pour plus de détails sur la façon dont la configuration runtime est stockée dans AWS AppConfig et comment les consommateurs côté serveur (fonctions Lambda, agents) peuvent la récupérer, consultez le guide Configuration Runtime.

Configuration runtime locale

Lors de l’exécution du serveur de développement local, vous aurez besoin d’un fichier runtime-config.json dans votre répertoire public pour que votre site local connaisse les URLs des backends, la configuration d’identité, etc.

Votre projet de site est configuré avec une cible load:runtime-config que vous pouvez utiliser pour récupérer le fichier runtime-config.json d’une application déployée :

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"

Noms d’étape personnalisés

CDK

Si vous modifiez le préfixe des noms de stage dans le src/main.ts de votre projet d’infrastructure, vous devrez mettre à jour la cible load:runtime-config dans le fichier project.json de votre site en conséquence.

De plus, notez que la cible load:runtime-config suppose qu’un seul stage de votre application est déployé dans l’environnement pour lequel vous avez des credentials AWS. Vous devrez ajuster la commande si vous déployez plusieurs stages dans le même compte et région.

Terraform

Pour les projets Terraform, la cible load:runtime-config copie le fichier runtime-config.json créé après votre dernier terraform apply local.

Serveur de développement local

La commande canonique pour le développement local est dev, qui démarre votre site web (et tous les serveurs locaux pour les APIs que vous y avez connectées) avec une seule commande :

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

La cible serve est également disponible lorsque vous devez contrôler quelle partie de votre application s’exécute localement par rapport à l’infrastructure AWS déployée. Pour un aperçu plus large du développement local entre projets connectés, y compris le comportement de dev pour les projets avec plusieurs composants, consultez le guide Développement local.

Cible Serve

La cible serve démarre un serveur de développement local pour votre site. Cette cible nécessite que vous ayez déployé toute infrastructure de support avec laquelle le site interagit, et que vous ayez chargé la configuration runtime locale.

Vous pouvez exécuter cette cible avec la commande :

pnpm

pnpm nx serve <my-website>

yarn

yarn nx serve <my-website>

npm

npx nx serve <my-website>

bun

bunx nx serve <my-website>

Cette cible est utile pour travailler sur des modifications du site tout en pointant vers des APIs “réelles” déployées et d’autres infrastructures.

Cible Dev

La cible dev démarre un serveur de développement local pour votre site (avec le MODE Vite défini sur local-dev), ainsi que des serveurs locaux pour les APIs connectées via le générateur Connection.

Lorsque le serveur local est lancé via cette cible, le runtime-config.json est automatiquement remplacé pour pointer vers les URLs des APIs locales.

Vous pouvez exécuter cette cible avec la commande :

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

Cette cible est utile lorsque vous travaillez à la fois sur votre site et vos APIs et souhaitez itérer rapidement sans déployer l’infrastructure.

Script dev de l’espace de travail

Le package.json racine de votre espace de travail inclut un script dev qui exécute la cible dev pour chaque projet qui en possède une :

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Cela démarre le serveur de développement local pour votre site web (et tous les autres projets avec une cible dev) en une seule commande. Pour exécuter uniquement ce site web, utilisez sa propre cible dev (par exemple nx dev <my-website>).

Authentification simulée

Dans ce mode, si aucun runtime-config.json n’est présent et que vous avez configuré l’authentification Cognito (via le générateur ts#website#auth), la connexion sera ignorée et les requêtes vers vos serveurs locaux n’incluront pas d’en-têtes d’authentification.

Pour activer la connexion et l’authentification pour dev, déployez votre infrastructure et chargez la configuration runtime.

Comportement de Dev

Lors de l’exécution avec dev, vous pouvez spécifier toutes les variables d’environnement requises par vos APIs pour pointer vers d’autres ressources AWS déployées, par exemple :

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>

Notez que vos serveurs d’API locaux s’exécuteront avec les credentials AWS que vous avez configurés localement.

Build

Vous pouvez builder votre site avec la cible build. Cela exécute les cibles bundle, compile, test et lint, effectuant la vérification de types, le bundling, les tests et le linting de votre site.

pnpm

pnpm nx build <my-website>

yarn

yarn nx build <my-website>

npm

npx nx build <my-website>

bun

bunx nx build <my-website>

La cible bundle utilise Vite pour créer un bundle de production dans le répertoire dist/packages/<my-website>/bundle. C’est l’artefact déployable consommé par votre infrastructure de site web. Vous pouvez l’exécuter seule :

pnpm

pnpm nx bundle <my-website>

yarn

yarn nx bundle <my-website>

npm

npx nx bundle <my-website>

bun

bunx nx bundle <my-website>

Tests

Tester votre site fonctionne comme pour un projet TypeScript standard. Consultez le guide de projet TypeScript pour plus de détails.

Pour les tests spécifiques à React, React Testing Library est déjà installé et disponible. Consultez la documentation React Testing Library pour son utilisation.

Vous pouvez exécuter les tests avec la cible 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>

Déploiement du site

Le générateur de site React crée une infrastructure CDK ou Terraform en fonction du iacProvider sélectionné. Vous pouvez l’utiliser pour déployer votre site.

CDK

Pour déployer votre site, nous recommandons d’utiliser le générateur ts#infra pour créer une application CDK.

Vous pouvez utiliser le construct CDK généré dans packages/common/constructs pour déployer votre site.

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

Ceci configure :

1. Un bucket S3 pour héberger les fichiers statiques
2. Une distribution CloudFront pour la diffusion globale
3. Un Web ACL WAF pour la sécurité
4. Une Origin Access Control pour l’accès sécurisé à S3
5. Déploiement automatique des fichiers et configuration runtime

Terraform

Pour déployer votre site, nous recommandons d’utiliser le générateur terraform#project pour créer un projet Terraform.

Vous pouvez utiliser le module Terraform généré dans packages/common/terraform pour déployer votre site.

packages/infra/src/main.tf

# Déployer le site
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
}

Ceci configure :

1. Un bucket S3 pour héberger les fichiers statiques
2. Une distribution CloudFront pour la diffusion globale
3. Un Web ACL WAF pour la sécurité (déployé en us-east-1)
4. Une Origin Access Control pour l’accès sécurisé à S3
5. Déploiement automatique des fichiers et configuration runtime

Région du fournisseur WAF

Le provider aws.us_east_1 est requis pour les ressources CloudFront et WAF qui doivent être déployées en région us-east-1. Assurez-vous que votre configuration Terraform inclut ce provider :

packages/infra/src/providers.tf

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

Connexions

Utilisez le générateur connection pour intégrer ce projet avec d’autres dans votre espace de travail. Les connexions suivantes impliquent ce projet :

React vers tRPCAppeler une API tRPC depuis un site React

React vers FastAPIAppeler une API Python FastAPI depuis un site React

React vers Smithy APIAppeler une API Smithy depuis un site React

React vers Python AgentAppeler un Python Agent depuis un site React

React vers TypeScript AgentAppeler un TypeScript Agent depuis un site React

React vers AG-UI AgentAppeler un Agent exposant le protocole AG-UI depuis un site React via CopilotKit

id>