Aller au contenu

Site Web React

Filter this guidePick generator option values to hide sections that don't apply.

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.

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

Terminal window
pnpm nx g @aws/nx-plugin:ts#website --framework=react
Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés
Terminal window
pnpm nx g @aws/nx-plugin:ts#website --framework=react --dry-run
ParamètreTypePar défautDescription
name Requisstring-Le nom de l'application.
framework reactreactLe framework frontend à utiliser.
directory stringpackagesLe 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 | shadcnshadcnLe fournisseur UX préféré.
tailwind booleantrueActiver TailwindCSS pour un style utilitaire.
tanstackRouter booleantrueActiver le routeur Tanstack pour un routage type-safe.
infra cloudfront-s3 | nonecloudfront-s3Le type d'infrastructure pour déployer votre site web.
iac inherit | cdk | terraforminheritLe fournisseur IaC préféré. Par défaut, il est hérité de votre sélection initiale.
preferInstallDependencies booleantrueIndique 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.

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

É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

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

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

Web BrowserWAFCloudFrontStatic Assets(S3)

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

ux = cloudscape

Vous pouvez vous référer à la documentation Cloudscape pour plus de détails sur les composants disponibles et comment les utiliser.

ux = shadcn

Vous pouvez vous référer à la documentation shadcn/ui pour plus de détails sur les composants disponibles et comment les utiliser.

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

  1. Exécuter le serveur de développement local
  2. Créer un nouveau fichier <page-name>.tsx dans src/routes, avec sa position dans l’arborescence de fichiers représentant le chemin
  3. Remarquez qu’une Route et un RouteComponent sont automatiquement générés pour vous. 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 ...
// 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.

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.

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

Cela configure :

  1. Un bucket S3 pour héberger vos fichiers de site Web statique
  2. Une distribution CloudFront pour la diffusion de contenu globale
  3. Une Web ACL WAF pour la protection de sécurité
  4. Un contrôle d’accès d’origine pour un accès S3 sécurisé
  5. Le déploiement automatique des fichiers du site Web et de la configuration d’exécution

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 :

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

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 :

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

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

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 :

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

Vous devrez également créer des enregistrements DNS (par exemple dans Route 53) pointant votre domaine vers la distribution CloudFront.

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.

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.

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(),
});
}
}

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

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 :

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

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 :

Terminal window
pnpm 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.

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 :

Terminal window
pnpm 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.

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 :

Terminal window
pnpm 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.

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.

Terminal window
pnpm 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 :

Terminal window
pnpm 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 :

Terminal window
pnpm nx test <my-website>

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 :

tRPC
React to tRPCCall a tRPC API from a React website
FastAPI
React to FastAPICall a Python FastAPI from a React website
Smithy
React to Smithy APICall a Smithy API from a React website
Strands AgentsPython
React to Python AgentCall a Python Agent from a React website
Strands AgentsTypeScript
React to TypeScript AgentCall a TypeScript Agent from a React website
CopilotKit
React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit
Amazon Bedrock AgentCore Gateway
React Website to AgentCore GatewayConnect a React website to agents through an AgentCore Gateway