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 el enrutamiento tipado.

Nota

Si bien este generador configura CloudScape, en esencia es un generador de proyectos React, y puedes modificar tu código para migrar a un sistema de diseño o biblioteca de componentes alternativo si lo deseas.

Uso

Generar un sitio web React

Puedes generar un nuevo sitio web React de dos formas:

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

yarn

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

npm

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

bun

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.

Salida 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 fuente 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

Implementando tu sitio web React

La documentación de React es un buen punto de partida para aprender los fundamentos. 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:

1. Ejecutar el servidor de desarrollo local
2. Crear un nuevo archivo <nombre-pagina>.tsx en src/routes, donde su posición en el árbol de archivos representa la ruta
3. 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 acceder a detalles como URLs de APIs que no se conocen hasta el despliegue.

Infraestructura

El construct CDK RuntimeConfig se usa para añadir y recuperar configuración. Los constructs generados por @aws/nx-plugin (como APIs tRPC y FastAPIs) añadirán automáticamente valores al RuntimeConfig.

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

    // 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 declarar tu sitio web después de los constructs que añaden al RuntimeConfig, de lo contrario faltarán en tu archivo runtime-config.json.

Código del sitio web

En tu sitio web, usa el hook useRuntimeConfig para obtener valores de la configuració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 el sitio local conozca las URLs de backend y configuración de identidad.

Tu proyecto incluye un target load:runtime-config para descargar el archivo desde una aplicación desplegada:

pnpm

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

yarn

yarn nx run <my-website>:"load:runtime-config"

npm

npx nx run <my-website>:"load:runtime-config"

bun

bunx nx run <my-website>:"load:runtime-config"

Si cambias el nombre de tu stack en src/main.ts de tu proyecto de infraestructura, debes actualizar el target load:runtime-config en el archivo project.json de tu sitio web con el nuevo nombre del stack.

Servidor de desarrollo local

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

Target Serve

El target serve inicia un servidor de desarrollo local. Requiere tener desplegada cualquier infraestructura de soporte y haber cargado la configuración local.

Ejecútalo con:

pnpm

pnpm nx run <my-website>:serve

yarn

yarn nx run <my-website>:serve

npm

npx nx run <my-website>:serve

bun

bunx nx run <my-website>:serve

Útil para trabajar en cambios del sitio apuntando a APIs reales desplegadas.

Target Serve Local

El target serve-local inicia un servidor local (con Vite MODE en serve-local) y servidores locales para APIs conectadas mediante el generador de conexión de APIs.

En este modo, runtime-config.json se sobrescribe automáticamente para apuntar a URLs locales.

Ejecútalo con:

pnpm

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

yarn

yarn nx run <my-website>:serve-local

npm

npx nx run <my-website>:serve-local

bun

bunx nx run <my-website>:serve-local

Útil para iterar rápidamente entre sitio web y API sin desplegar infraestructura.

En este modo sin runtime-config.json, si tienes autenticación Cognito (via generador de autenticación), el login se omitirá y las peticiones no incluirán headers de autenticación.

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

Construcción

Construye tu sitio web con el target build. Esto crea un bundle de producción en dist/packages/<my-website>/bundle usando Vite, junto con verificación de tipos y linting.

pnpm

pnpm nx run <my-website>:build

yarn

yarn nx run <my-website>:build

npm

npx nx run <my-website>:build

bun

bunx nx run <my-website>:build

Pruebas

Las pruebas siguen patrones estándar de TypeScript. Consulta la guía de proyectos TypeScript.

Para pruebas específicas de React, React Testing Library está instalado. Consulta su documentación.

Ejecuta pruebas con:

pnpm

pnpm nx run <my-website>:test

yarn

yarn nx run <my-website>:test

npm

npx nx run <my-website>:test

bun

bunx nx run <my-website>:test

Despliegue del sitio web

Recomendamos usar el generador de infraestructura TypeScript para crear una aplicación CDK.

Usa el construct generado en packages/common/constructs para desplegar tu sitio:

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