Aller au contenu

Site Web React

Ce générateur crée un nouveau site web React configuré avec CloudScape, ainsi que l’infrastructure AWS CDK 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 typé.

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

  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
    • Cliquez sur Generate
    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.

    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

    Le générateur créera également le code d’infrastructure CDK pour déployer votre site web dans le répertoire packages/common/constructs :

    • Répertoiresrc
      • Répertoireapp
        • Répertoirestatic-websites
          • <name>.ts Infrastructure spécifique à votre site web
      • Répertoirecore
        • static-website.ts Construct générique StaticWebsite

    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.

    Votre site web 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ù sa position dans l’arborescence représente le chemin
    3. Une Route et un RouteComponent sont générés automatiquement. Vous pouvez commencer à construire votre page ici !

    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}>Soumettre</Button>
    </>
    )
    };

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

    La configuration de votre infrastructure AWS CDK est fournie à votre site web via une Configuration à l’exécution. Cela permet à votre site web d’accéder à des détails comme les URLs d’API qui ne sont connus qu’après le déploiement.

    Le construct CDK RuntimeConfig peut être utilisé pour ajouter et récupérer des configurations dans votre infrastructure CDK. Les constructs CDK générés par @aws/nx-plugin (comme les API tRPC et FastAPIs) ajouteront automatiquement les valeurs appropriées au RuntimeConfig.

    Votre construct CDK de site web déploiera la configuration d’exécution sous forme de 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 d'exécution dans runtime-config.json
    new MyWebsite(this, 'MyWebsite');
    }
    }

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

    Dans votre site web, vous pouvez utiliser le hook useRuntimeConfig pour récupérer les valeurs de la configuration d’exécution :

    import { useRuntimeConfig } from '../hooks/useRuntimeConfig';
    const MyComponent = () => {
    const runtimeConfig = useRuntimeConfig();
    // Accédez aux valeurs de la configuration ici
    const apiUrl = runtimeConfig.apis.MyApi;
    };

    Pour utiliser le serveur de développement local, vous aurez besoin d’un fichier runtime-config.json dans votre répertoire public afin que votre site web local connaisse les URLs des backends, la configuration d’identité, etc.

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

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

    Si vous modifiez le nom de votre stack 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 web avec le nom de la stack à utiliser.

    Vous pouvez lancer un serveur de développement local en utilisant les cibles serve ou serve-local.

    La cible serve démarre un serveur de développement local pour votre site web. Cette cible nécessite d’avoir déployé les infrastructures annexes avec lesquelles le site web interagit, et d’avoir chargé la configuration d’exécution locale.

    Vous pouvez exécuter cette cible avec la commande :

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

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

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

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

    Vous pouvez exécuter cette cible avec la commande :

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

    Cette cible est utile lorsque vous travaillez à la fois sur votre site web 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 web 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 d’exécution.

    Vous pouvez builder votre site web 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.

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

    Tester votre site web est similaire à l’écriture de tests dans un projet TypeScript standard. Reportez-vous au guide des projets 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 vos tests avec la cible test :

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

    Pour déployer votre site web, nous recommandons d’utiliser le générateur d’infrastructure TypeScript pour créer une application CDK.

    Vous pouvez utiliser le construct CDK généré dans packages/common/constructs pour déployer votre site 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');
    }
    }