Site Web React

Ce générateur crée un nouveau site React configuré avec CloudScape, 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.

Note

Bien que ce générateur vous configure avec CloudScape, il s’agit fondamentalement d’un générateur de projet React. Vous pouvez modifier votre code pour passer à un autre système de design ou bibliothèque de composants si vous le souhaitez.

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#react-website
5. Remplissez les paramètres requis
6. Cliquez sur Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

Options

Paramètre	Type	Par défaut	Description
name Requis	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.
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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 CloudScape et la barre de navigation
  • Répertoirehooks

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

    • Répertoirewelcome

      • index.tsx Exemple de route (ou page) pour @tanstack/react-router
  • styles.css Styles globaux
• vite.config.ts 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

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

Note

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

Note

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

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. Vous pouvez consulter la documentation CloudScape pour les détails sur les composants disponibles et leur utilisation.

Routes

Création d’une route/page

Votre site CloudScape 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 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 } from ':my-scope/common-constructs';

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

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

    // Déploie automatiquement la config runtime dans runtime-config.json
    new MyWebsite(this, 'MyWebsite');
  }
}

Attention

Vous devez vous assurer de déclarer votre site web après tout construct qui ajoute des éléments au RuntimeConfig, sans quoi ils seront absents du fichier runtime-config.json.

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#trpc-api et py#fast-api) ajoutent automatiquement les valeurs appropriées à la configuration runtime.

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

packages/infra/src/main.tf

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

# 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]
}

Attention

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 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"

Note

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

Vous pouvez lancer un serveur de développement local en utilisant les cibles serve ou serve-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 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

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

Cible Serve Local

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

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 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

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.

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 d’authentification pour site CloudScape), 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 en mode serve-local, déployez votre infrastructure et chargez la configuration runtime.

Build

Vous pouvez builder votre site avec la cible build. Cela utilise Vite pour créer un bundle de production dans le répertoire dist/packages/<my-website>/bundle, ainsi que la vérification de types, la compilation et le linting.

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

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 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

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

Note

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"
}