Site Web React
Ce générateur crée un nouveau site Web React avec shadcn/ui configuré par défaut, ainsi que l’infrastructure AWS CDK ou Terraform pour déployer votre site Web dans le cloud en tant que site Web 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.
Utilisation
Section intitulée « Utilisation »Générer un site Web React
Section intitulée « Générer un site Web React »Vous pouvez générer un nouveau site Web React de deux manières :
pnpm nx g @aws/nx-plugin:ts#website --framework=reactyarn nx g @aws/nx-plugin:ts#website --framework=reactnpx nx g @aws/nx-plugin:ts#website --framework=reactbunx nx g @aws/nx-plugin:ts#website --framework=reactVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés
pnpm nx g @aws/nx-plugin:ts#website --framework=react --dry-runyarn nx g @aws/nx-plugin:ts#website --framework=react --dry-runnpx nx g @aws/nx-plugin:ts#website --framework=react --dry-runbunx nx g @aws/nx-plugin:ts#website --framework=react --dry-run- Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
- Ouvrez la console Nx dans VSCode
- Cliquez sur
Generate (UI)dans la section "Common Nx Commands" - Recherchez
@aws/nx-plugin - ts#website - Remplissez les paramètres requis
- framework: react
- Cliquez sur
Generate
| 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
Section intitulée « Sortie du générateur »Le générateur créera la structure de projet suivante dans le répertoire <directory>/<name> :
- index.html HTML entry point
- public Static assets
Répertoiresrc
- main.tsx Application entry point with React setup
- config.ts Application configuration (eg. logo)
Répertoirecomponents
- AppLayout Components for the overall layout and navigation bar
Répertoirehooks
- useAppLayout.tsx Hook for adjusting the AppLayout from nested components (Cloudscape only)
Répertoireroutes
- 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
Infrastructure
Section intitulée « Infrastructure »Étant donné que ce générateur fournit de l’infrastructure en tant que code basée sur votre iac choisi, il créera un projet dans packages/common qui inclut les constructs CDK ou modules Terraform pertinents.
Le projet d’infrastructure en tant que code commun est structuré comme suit :
Répertoirepackages/common/constructs
Répertoiresrc
Répertoireapp/ Constructs pour l’infrastructure spécifique à un projet/générateur
- …
Répertoirecore/ Constructs génériques qui sont réutilisés par les constructs dans
app- …
- index.ts Entry point exporting constructs from
app
- project.json Project build targets and configuration
Répertoirepackages/common/terraform
Répertoiresrc
Répertoireapp/ Terraform modules for infrastructure specific to a project/generator
- …
Répertoirecore/ Generic modules which are reused by modules in
app- …
- project.json Project build targets and configuration
Le générateur crée l’infrastructure as code pour déployer votre site Web en fonction de votre iac sélectionné :
Répertoirepackages/common/constructs/src
Répertoireapp
Répertoirestatic-websites
- <name>.ts Infrastructure specific to your website
Répertoirecore
- static-website.ts Generic StaticWebsite construct
Répertoirepackages/common/terraform/src
Répertoireapp
Répertoirestatic-websites
Répertoire<name>
- <name>.tf Module specific to your website
Répertoirecore
Répertoirestatic-website
- static-website.tf Generic static website module
Architecture
Section intitulée « Architecture »Le site Web déployé a l’architecture suivante :
Implémenter votre site Web
Section intitulée « Implémenter votre site Web »La documentation React est un bon point de départ pour apprendre les bases de la construction avec React.
Vous pouvez vous référer à la documentation Cloudscape pour plus de détails sur les composants disponibles et comment les utiliser.
Vous pouvez vous référer à la documentation shadcn/ui pour plus de détails sur les composants disponibles et comment les utiliser.
Créer une route/page
Section intitulée « Créer une route/page »Votre site Web est livré avec TanStack Router configuré par défaut. Cela facilite l’ajout de nouvelles routes :
- Exécuter le serveur de développement local
- Créer un nouveau fichier
<page-name>.tsxdanssrc/routes, avec sa position dans l’arborescence de fichiers représentant le chemin - Remarquez qu’une
Routeet unRouteComponentsont automatiquement générés pour vous. Vous pouvez commencer à construire votre page ici !
Naviguer entre les pages
Section intitulée « Naviguer entre les 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 ... // 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> </> )};Pour plus de détails, consultez la documentation TanStack Router.
Déployer votre site Web
Section intitulée « Déployer votre site Web »Le générateur de site Web React crée l’infrastructure as code CDK ou Terraform en fonction de votre iac sélectionné. Vous pouvez l’utiliser pour déployer votre site Web.
Pour déployer votre site Web, 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é pour vous dans packages/common/constructs pour déployer votre site Web.
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'); }}Cela configure :
- Un bucket S3 pour héberger vos fichiers de site Web statique
- Une distribution CloudFront pour la diffusion de contenu globale
- Une Web ACL WAF pour la protection de sécurité
- Un contrôle d’accès d’origine pour un accès S3 sécurisé
- Le déploiement automatique des fichiers du site Web et de la configuration d’exécution
Pour déployer votre site Web, 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é pour vous dans packages/common/terraform pour déployer votre site Web.
# Deploy websitemodule "my_website" { source = "../../common/terraform/src/app/static-websites/my-website"
providers = { aws.us_east_1 = aws.us_east_1 }}Cela configure :
- Un bucket S3 pour héberger vos fichiers de site Web statique
- Une distribution CloudFront pour la diffusion de contenu globale
- Une Web ACL WAF pour la protection de sécurité (déployée dans us-east-1)
- Un contrôle d’accès d’origine pour un accès S3 sécurisé
- Le déploiement automatique des fichiers du site Web et de la configuration d’exécution
En-têtes de sécurité
Section intitulée « 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 XSS et le clickjacking, tout en permettant les connexions HTTPS et WSS afin que le site Web puisse appeler les points de terminaison de service AWS (tels que API Gateway, Cognito et Bedrock AgentCore) dont les URL ne sont connues qu’au moment du déploiement. Pour ajuster la politique (par exemple pour resserrer connect-src à vos origines spécifiques), modifiez la valeur content_security_policy dans votre static-website.ts (CDK) ou static-website.tf (Terraform) généré.
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.
La distribution CloudFront est protégée par une Web ACL AWS WAFv2 par défaut. La Web ACL utilise l’ensemble de règles par défaut géré par AWS (AWSManagedRulesCommonRuleSet et AWSManagedRulesKnownBadInputsRuleSet), offrant une protection contre les exploits Web courants, y compris le Top 10 OWASP.
Pour désactiver, définissez enableWaf sur false lorsque vous créez votre site Web :
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', ); }}Pour désactiver, définissez enable_waf sur false :
module "my_website" { source = "../../common/terraform/src/app/static-websites/my-website"
providers = { aws.us_east_1 = aws.us_east_1 } enable_waf = false}Chiffrement du bucket
Section intitulée « Chiffrement du bucket »Le bucket du site Web, le bucket de logs de la distribution CloudFront et le groupe CloudWatch Logs recevant leurs logs d’accès au serveur sont chiffrés avec une clé AWS KMS gérée par le client par défaut. Cette clé est créée automatiquement pour vous, avec la rotation de clé activée.
Si vous souhaitez utiliser une configuration de chiffrement différente, passez les props encryption, encryptionKey et enableKeyRotation lorsque vous créez votre site Web :
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, }); }}Pour utiliser votre propre clé KMS au lieu d’une créée automatiquement, passez encryptionKey :
new MyWebsite(this, 'MyWebsite', { encryptionKey: myKey,});enableKeyRotation (par défaut true) ne s’applique qu’à la clé créée automatiquement, c’est-à-dire lorsque encryption est BucketEncryption.KMS (par défaut) et qu’aucune encryptionKey n’est fournie :
new MyWebsite(this, 'MyWebsite', { enableKeyRotation: false,});Si vous souhaitez utiliser une configuration de chiffrement différente, définissez les variables encryption, kms_key_arn, create_kms_key et enable_key_rotation :
module "my_website" { source = "../../common/terraform/src/app/static-websites/my-website"
providers = { aws.us_east_1 = aws.us_east_1 } encryption = "S3_MANAGED"}Pour utiliser votre propre clé KMS au lieu d’une créée automatiquement, passez kms_key_arn et définissez create_kms_key sur false :
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}Une clé fournie par le client doit déjà accorder aux principaux de service CloudWatch Logs, S3 et CloudFront les permissions dont ils ont besoin dans sa propre politique de clé.
enable_key_rotation (par défaut true) ne s’applique qu’à la clé créée automatiquement, c’est-à-dire lorsque encryption est "KMS" (par défaut) et que create_kms_key est true :
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}Domaine personnalisé et TLS
Section intitulée « Domaine personnalisé et TLS »Par défaut, la distribution utilise le nom de domaine CloudFront par défaut (*.cloudfront.net) et son certificat par défaut, qui ne prend pas en charge l’application d’une version TLS minimale de 1.2. Pour servir votre site Web depuis votre propre domaine, fournissez un certificat ACM (qui doit résider dans us-east-1 pour une utilisation avec CloudFront) et vos noms de domaine. Une version TLS minimale de 1.2 est alors appliquée pour les visiteurs :
Passez les props certificate et domainNames lorsque vous créez votre site Web :
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/...'), }); }}Définissez les variables custom_domain_names et acm_certificate_arn :
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/..."}Vous devrez également créer des enregistrements DNS (par exemple dans Route 53) pointant votre domaine vers la distribution CloudFront.
Configuration d’exécution
Section intitulée « Configuration d’exécution »La configuration de votre infrastructure est fournie à votre site Web via la Configuration d’exécution. Cela permet à votre site Web d’accéder à des détails tels que les URL d’API qui ne sont pas connus avant le déploiement de votre application.
Infrastructure
Section intitulée « Infrastructure »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 (tels que ts#api et py#api) ajouteront automatiquement les valeurs appropriées au RuntimeConfig.
Votre construct CDK de site Web déploiera l’espace de noms connection de la configuration d’exécution en tant que fichier runtime-config.json à la racine de votre bucket S3.
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(), }); }}Avec Terraform, la configuration d’exécution est gérée via les modules runtime-config. Les modules Terraform générés par les générateurs @aws/nx-plugin (tels que ts#api et py#api) ajouteront automatiquement les valeurs appropriées à la configuration d’exécution.
Votre module Terraform de site Web déploiera l’espace de noms connection de la configuration d’exécution en tant que fichier runtime-config.json à la racine de votre bucket S3.
module "asset_bucket" { source = "../../common/terraform/src/core/asset-bucket"}
# Automatically adds values to runtime configmodule "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.jsonmodule "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]}Code du site Web
Section intitulée « Code du site Web »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();
// Access values in the runtime config here const apiUrl = runtimeConfig.apis.MyApi;};Configuration d’exécution locale
Section intitulée « Configuration d’exécution 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 afin que votre site Web local connaisse les URL backend, la configuration d’identité, etc.
Votre projet de site Web est configuré avec une cible load-runtime-config que vous pouvez utiliser pour télécharger le fichier runtime-config.json depuis une application déployée :
pnpm nx load-runtime-config <my-website>yarn nx load-runtime-config <my-website>npx nx load-runtime-config <my-website>bunx nx load-runtime-config <my-website>Serveur de développement local
Section intitulée « 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 API auxquelles vous l’avez connecté) avec une seule commande :
pnpm nx dev <my-website>yarn nx dev <my-website>npx nx dev <my-website>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 au pointage vers l’infrastructure AWS déployée. Pour un aperçu plus large du développement local à travers les projets connectés, y compris comment dev se comporte pour les projets avec plusieurs composants, consultez le guide Développement local.
Cible Serve
Section intitulée « Cible Serve »La cible serve démarre un serveur de développement local pour votre site Web. Cette cible nécessite que vous ayez déployé toute infrastructure de support avec laquelle le site Web interagit, et que vous ayez chargé la configuration d’exécution locale.
Vous pouvez exécuter cette cible avec la commande suivante :
pnpm nx serve <my-website>yarn nx serve <my-website>npx nx serve <my-website>bunx nx serve <my-website>Cette cible est utile pour travailler sur les modifications du site Web tout en pointant vers des API “réelles” déployées et d’autres infrastructures.
Cible Dev
Section intitulée « Cible Dev »La cible dev démarre un serveur de développement local pour votre site Web (avec Vite MODE défini sur local-dev), ainsi que le démarrage de tous les serveurs locaux pour les API auxquelles vous avez connecté votre site Web via le générateur Connection.
Lorsque votre serveur de site Web local est exécuté via cette cible, runtime-config.json est automatiquement remplacé pour pointer vers vos URL d’API en cours d’exécution localement.
Vous pouvez exécuter cette cible avec la commande suivante :
pnpm nx dev <my-website>yarn nx dev <my-website>npx nx dev <my-website>bunx nx dev <my-website>Cette cible est utile lorsque vous travaillez sur votre site Web et votre API et souhaitez itérer rapidement sans déployer votre infrastructure.
Authentification simulée
Lorsqu’il est exécuté dans ce mode et qu’aucun runtime-config.json n’est présent, si 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 d’exécution.
Building
Section intitulée « Building »Vous pouvez construire votre site Web en utilisant la cible build. Cela exécute les cibles bundle, compile, test et lint, vérifiant les types, regroupant, testant et lintant votre site Web.
pnpm nx build <my-website>yarn nx build <my-website>npx nx build <my-website>bunx nx build <my-website>La cible bundle utilise Vite pour créer un bundle de production dans le répertoire racine dist/packages/<my-website>/bundle. C’est l’artefact déployable consommé par votre infrastructure de site Web. Vous pouvez l’exécuter seul :
pnpm nx bundle <my-website>yarn nx bundle <my-website>npx nx bundle <my-website>bunx nx bundle <my-website>Tester votre site Web ressemble beaucoup à l’écriture de tests dans un projet TypeScript standard, veuillez donc vous référer au guide du projet TypeScript pour plus de détails.
Pour les tests spécifiques à React, React Testing Library est déjà installé et disponible pour que vous puissiez l’utiliser pour écrire des tests. Pour plus de détails sur son utilisation, veuillez vous référer à la documentation React Testing Library.
Vous pouvez exécuter vos tests en utilisant la cible test :
pnpm nx test <my-website>yarn nx test <my-website>npx nx test <my-website>bunx nx test <my-website>Connexions
Section intitulée « 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 :
