Sitio web de React

Este generador crea un nuevo sitio web con React configurado con CloudScape, junto con la infraestructura de AWS CDK para desplegar tu sitio web en la nube como un sitio estático alojado en S3, servido por CloudFront y protegido por WAF.

La aplicación generada utiliza Vite como herramienta de construcción y empaquetado. Emplea TanStack Router para enrutamiento tipado.

Uso

Generar un sitio web React

Puedes generar un nuevo sitio web React de dos maneras:

VSCode
CLI

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - ts#react-website
Complete los parámetros requeridos
Haga clic en Generate

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

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

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

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

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

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

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	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.

Resultado del generador

El generador creará la siguiente estructura de proyecto en el directorio <directory>/<name>:

index.html Punto de entrada HTML
public Assets estáticos
Directorysrc
- main.tsx Punto de entrada de la aplicación con configuración React
- config.ts Configuración de la aplicación (ej. logo)
- Directorycomponents
  - AppLayout Componentes para el layout general de CloudScape y barra de navegación
- Directoryhooks
  - useAppLayout.tsx Hook para ajustar el AppLayout desde componentes anidados
- Directoryroutes
  - Directorywelcome
    index.tsx Ruta (o página) de ejemplo para @tanstack/react-router
- styles.css Estilos globales
vite.config.ts Configuración de Vite y Vitest
tsconfig.json Configuración base de TypeScript para código y tests
tsconfig.app.json Configuración TypeScript para código fuente
tsconfig.spec.json Configuración TypeScript para tests

El generador también creará código de infraestructura CDK para desplegar tu sitio web en el directorio packages/common/constructs:

Directorysrc
- Directoryapp
  - Directorystatic-websites
    <name>.ts Infraestructura específica de tu sitio web
- Directorycore
  - static-website.ts Construct genérico StaticWebsite

Implementación de tu sitio web React

La documentación de React es un buen punto de partida para aprender los fundamentos de desarrollo con React. Puedes consultar la documentación de CloudScape para detalles sobre los componentes disponibles y su uso.

Rutas

Crear una ruta/página

Tu sitio CloudScape incluye TanStack Router configurado por defecto. Esto facilita añadir nuevas rutas:

Ejecutar el servidor de desarrollo local
Crear un nuevo archivo <nombre-página>.tsx en src/routes, donde su posición en el árbol de archivos representa la ruta
Notarás que se generan automáticamente un Route y RouteComponent. ¡Puedes empezar a construir tu página aquí!

Navegar entre páginas

Puedes usar el componente Link o el hook useNavigate para navegar entre páginas:

import { Link, useNavigate } from '@tanstack/react-router';

export const MyComponent = () => {
  const navigate = useNavigate();

  const submit = async () => {
    const id = await ...
    // Usar `navigate` para redireccionar después de una acción asíncrona
    navigate({ to: '/products/$id', { params: { id }} });
  };

  return (
    <>
      <Link to="/products">Cancelar</Link>
      <Button onClick={submit}>Enviar</Button>
    </>
  )
};

Para más detalles, consulta la documentación de TanStack Router.

Configuración en tiempo de ejecución

La configuración de tu infraestructura AWS CDK se provee a tu sitio web mediante Runtime Configuration. Esto permite que tu sitio web acceda a detalles como URLs de APIs que no se conocen hasta que la aplicación es desplegada.

Infraestructura

El constructo CDK RuntimeConfig se puede usar para añadir y recuperar configuración en tu infraestructura CDK. Los constructos CDK generados por @aws/nx-plugin (como APIs tRPC y FastAPIs) añadirán automáticamente valores apropiados al RuntimeConfig.

Tu constructo CDK del sitio web desplegará la configuración de tiempo de ejecución como un archivo runtime-config.json en la raíz de tu 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);

    // Añade automáticamente valores al RuntimeConfig
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });

    // Despliega automáticamente la configuración en runtime-config.json
    new MyWebsite(this, 'MyWebsite');
  }
}

Debes asegurarte de declarar tu sitio web después de cualquier constructo que añada al RuntimeConfig, de lo contrario faltarán en tu archivo runtime-config.json.

Código del sitio web

En tu sitio web, puedes usar el hook useRuntimeConfig para obtener valores de la configuración de tiempo de ejecución:

import { useRuntimeConfig } from '../hooks/useRuntimeConfig';

const MyComponent = () => {
  const runtimeConfig = useRuntimeConfig();

  // Accede a los valores de la configuración aquí
  const apiUrl = runtimeConfig.apis.MyApi;
};

Configuración local en tiempo de ejecución

Al ejecutar el servidor de desarrollo local, necesitarás un archivo runtime-config.json en tu directorio public para que tu sitio local conozca las URLs de backend, configuración de identidad, etc.

Tu proyecto de sitio web está configurado con un target load:runtime-config que puedes usar para descargar el archivo runtime-config.json de una aplicación desplegada:

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 cambias el prefijo de tus stage names en el src/main.ts de tu proyecto de infraestructura, deberás actualizar el target load:runtime-config en el archivo project.json de tu sitio web.

Además, es importante notar que el target load:runtime-config asume que un único stage de tu aplicación está desplegado en el entorno para el que tienes credenciales AWS. Deberás ajustar el comando si despliegas múltiples stages en la misma cuenta y región.

Servidor de desarrollo local

Puedes ejecutar un servidor de desarrollo local usando los targets serve o serve-local.

Target Serve

El target serve inicia un servidor de desarrollo local para tu sitio web. Este target requiere que hayas desplegado cualquier infraestructura de soporte con la que interactúa el sitio web, y que hayas cargado la configuración local de tiempo de ejecución.

Puedes ejecutar este target con el siguiente comando:

pnpm nx run <my-website>:serve

yarn nx run <my-website>:serve

npx nx run <my-website>:serve

bunx nx run <my-website>:serve

Este target es útil para trabajar en cambios del sitio web apuntando a APIs “reales” desplegadas y otra infraestructura.

Target Serve Local

El target serve-local inicia un servidor de desarrollo local para tu sitio web (con Vite MODE establecido en serve-local), además de iniciar servidores locales para APIs conectadas a tu sitio web mediante el generador de Conexión API.

Cuando el servidor local se ejecuta mediante este target, el runtime-config.json se sobrescribe automáticamente para apuntar a las URLs de tus APIs locales.

Puedes ejecutar este target con el siguiente comando:

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

Este target es útil cuando trabajas simultáneamente en tu sitio web y API, y deseas iterar rápidamente sin desplegar infraestructura.

Cuando se ejecuta en este modo y no existe runtime-config.json, si has configurado Autenticación Cognito (mediante el generador CloudScape Website Auth), el login se omitirá y las peticiones a tus servidores locales no incluirán headers de autenticación.

Para habilitar login y autenticación en serve-local, despliega tu infraestructura y carga la configuración de tiempo de ejecución.

Construcción

Puedes construir tu sitio web usando el target build. Esto utiliza Vite para crear un bundle de producción en el directorio dist/packages/<my-website>/bundle, además de verificar tipos, compilar y hacer linting de tu sitio web.

pnpm nx run <my-website>:build

yarn nx run <my-website>:build

npx nx run <my-website>:build

bunx nx run <my-website>:build

Pruebas

Probar tu sitio web es similar a escribir tests en un proyecto TypeScript estándar, por favor consulta la guía de proyectos TypeScript para más detalles.

Para pruebas específicas de React, React Testing Library ya está instalado y disponible para escribir tests. Para más detalles sobre su uso, consulta la documentación de React Testing Library.

Puedes ejecutar tus tests usando el target test:

pnpm nx run <my-website>:test

yarn nx run <my-website>:test

npx nx run <my-website>:test

bunx nx run <my-website>:test

Despliegue de tu sitio web

Para desplegar tu sitio web, recomendamos usar el Generador de Infraestructura TypeScript para crear una aplicación CDK.

Puedes usar el constructo CDK generado para ti en packages/common/constructs para desplegar tu sitio 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');
  }
}