Site CloudScape
Ce générateur crée un nouveau site React configuré avec CloudScape, ainsi que l’infrastructure AWS CDK pour déployer votre site 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 emploie TanStack Router pour le routage typé.
Utilisation
Générer un site CloudScape
Vous pouvez générer un nouveau site CloudScape de deux manières :
- 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#cloudscape-website
- Remplissez les paramètres requis
- Cliquez sur
Generate
pnpm nx g @aws/nx-plugin:ts#cloudscape-website
yarn nx g @aws/nx-plugin:ts#cloudscape-website
npx nx g @aws/nx-plugin:ts#cloudscape-website
bunx nx g @aws/nx-plugin:ts#cloudscape-website
Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés
pnpm nx g @aws/nx-plugin:ts#cloudscape-website --dry-run
yarn nx g @aws/nx-plugin:ts#cloudscape-website --dry-run
npx nx g @aws/nx-plugin:ts#cloudscape-website --dry-run
bunx nx g @aws/nx-plugin:ts#cloudscape-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. |
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
Le générateur créera également le code d’infrastructure CDK pour déployer votre site dans le répertoire packages/common/constructs
:
Répertoiresrc
Répertoireapp
Répertoirestatic-websites
- <name>.ts Infrastructure spécifique à votre site
Répertoirecore
- static-website.ts Construct générique StaticWebsite
Implémentation de votre site CloudScape
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 préconfiguré avec TanStack Router, ce qui facilite l’ajout de nouvelles routes :
- Lancer le serveur de développement local
- Créer un nouveau fichier
<page-name>.tsx
danssrc/routes
, où l’arborescence représente le chemin - Une
Route
et unRouteComponent
sont générés automatiquement. Vous pouvez commencer à développer votre page ici !
Navigation entre pages
Utilisez 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 AWS CDK est fournie à votre site via la Configuration Runtime. Cela permet d’accéder à des détails comme les URLs d’API qui ne sont connus qu’après le déploiement.
Infrastructure
Le construct CDK RuntimeConfig
permet d’ajouter et récupérer des valeurs de configuration. Les constructs générés par @aws/nx-plugin
(comme les API tRPC et FastAPIs) ajoutent automatiquement les valeurs appropriées au RuntimeConfig
.
Votre construct CDK de site déploie la configuration runtime dans un fichier runtime-config.json
à la racine de votre bucket S3.
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'); }}
Vous devez déclarer votre site après les constructs qui ajoutent des valeurs au RuntimeConfig
, sans quoi elles seront absentes du fichier runtime-config.json
.
Code du site
Dans votre site, utilisez le hook useRuntimeConfig
pour récupérer les valeurs de configuration :
import { useRuntimeConfig } from '../hooks/useRuntimeConfig';
const MyComponent = () => { const runtimeConfig = useRuntimeConfig();
// Accédez aux valeurs de configuration ici const apiUrl = runtimeConfig.apis.MyApi;};
Configuration runtime locale
Pour le serveur de développement local, vous aurez besoin d’un fichier runtime-config.json
dans votre répertoire public
afin que votre site local connaisse les URLs des backends, la configuration d’authentification, etc.
Votre projet de site inclut une cible load:runtime-config
pour télécharger le fichier runtime-config.json
depuis une application déployée :
pnpm nx run <my-website>:"load:runtime-config"
yarn nx run <my-website>:"load:runtime-config"
npx nx run <my-website>:"load:runtime-config"
bunx 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, mettez à jour la cible load:runtime-config
dans le fichier project.json
de votre site avec le nom de la stack à utiliser.
Serveur de développement local
Vous pouvez lancer un serveur de développement local avec 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 les infrastructures dépendantes soient déployées et que la configuration runtime locale soit chargée.
Exécutez cette cible avec :
pnpm nx run <my-website>:serve
yarn nx run <my-website>:serve
npx nx run <my-website>:serve
bunx nx run <my-website>:serve
Utile pour modifier le site tout en pointant vers des APIs déployées.
Cible Serve Local
La cible serve-local
démarre un serveur local (avec le MODE Vite défini sur serve-local
), ainsi que les serveurs locaux des APIs connectées via le générateur API Connection.
Dans ce mode, le runtime-config.json
est automatiquement remplacé pour pointer vers les URLs locales des APIs.
Exécutez cette cible avec :
pnpm nx run <my-website>:serve-local
yarn nx run <my-website>:serve-local
npx nx run <my-website>:serve-local
bunx nx run <my-website>:serve-local
Utile pour développer simultanément sur le site et les APIs sans déployer l’infrastructure.
Dans ce mode sans runtime-config.json
, si vous avez configuré l’authentification Cognito (via le générateur CloudScape Website Auth), le login sera désactivé et les requêtes locales n’incluront pas d’en-têtes d’authentification.
Pour activer l’authentification en mode serve-local
, déployez l’infrastructure et chargez la configuration runtime.
Build
Utilisez la cible build
pour construire votre site. Cela génère un bundle de production via Vite dans dist/packages/<my-website>/bundle
, avec vérification de types et linting.
pnpm nx run <my-website>:build
yarn nx run <my-website>:build
npx nx run <my-website>:build
bunx nx run <my-website>:build
Tests
Les tests fonctionnent comme dans un projet TypeScript standard. Consultez le guide des projets TypeScript pour plus de détails.
React Testing Library est préinstallé pour les tests React. Voir la documentation React Testing Library.
Exécutez les tests avec :
pnpm nx run <my-website>:test
yarn nx run <my-website>:test
npx nx run <my-website>:test
bunx nx run <my-website>:test
Déploiement du site
Nous recommandons d’utiliser le générateur d’infrastructure TypeScript pour créer une application CDK.
Utilisez le construct généré dans packages/common/constructs
pour déployer votre site :
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'); }}