Sitio web de React

Este generador crea un nuevo sitio web en React configurado con CloudScape, junto con la infraestructura de AWS CDK o Terraform 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.

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.
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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 de 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 de TypeScript para código fuente
• tsconfig.spec.json Configuración de TypeScript para tests

Infraestructura

Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructos para infraestructura específica de un proyecto/generador

      • …
    • Directorycore/ Constructos genéricos reutilizados por los constructos en app

      • …
    • index.ts Punto de entrada que exporta los constructos de app
  • project.json Objetivos de compilación y configuración del proyecto

Nota

Este proyecto se genera utilizando el ts#project generator y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador

      • …
    • Directorycore/ Módulos genéricos reutilizados por los módulos en app

      • …
  • project.json Objetivos de compilación y configuración del proyecto

Nota

Este proyecto se genera utilizando el terraform#project generator y por lo tanto configura los mismos objetivos de compilación.

El generador crea infraestructura como código para desplegar tu sitio web según el iacProvider seleccionado:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorystatic-websites

      • <name>.ts Infraestructura específica de tu sitio web
  • Directorycore

    • static-website.ts Construct genérico StaticWebsite

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorystatic-websites

      • Directory<name>

        • <name>.tf Módulo específico para tu sitio web
  • Directorycore

    • Directorystatic-website

      • static-website.tf Módulo genérico de sitio web estático

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 la posición en el árbol de archivos representa la ruta
3. Observa 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 se provee al sitio web mediante Configuración en Tiempo de Ejecución. Esto permite acceder a detalles como URLs de API que no se conocen hasta el despliegue.

Infraestructura

CDK

El construct RuntimeConfig de CDK puede usarse para añadir y recuperar configuración. Los constructs generados por generadores @aws/nx-plugin (como ts#trpc-api y py#fast-api) añaden automáticamente valores al RuntimeConfig.

Tu construct CDK del 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');
  }
}

Precaución

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

Terraform

Con Terraform, la configuración se gestiona mediante módulos runtime-config. Los módulos generados por @aws/nx-plugin (como ts#trpc-api y py#fast-api) añaden automáticamente valores a la configuración.

Tu módulo Terraform del sitio web desplegará la configuración como archivo runtime-config.json en la raíz de tu bucket S3.

packages/infra/src/main.tf

# Añade valores a la configuración automáticamente
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"
}

# Despliega la configuración en runtime-config.json
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # Garantiza que la API se despliega primero
  depends_on = [module.my_api]
}

Precaución

Debes declarar tu módulo del sitio web después de cualquier módulo que añada a la configuración y configurar depends_on apropiado, de lo contrario faltarán valores en 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

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 del backend, configuración de identidad, etc.

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"

Nota

CDK

Si cambias el prefijo de stages en src/main.ts de tu infraestructura, debes actualizar el target load:runtime-config en el project.json de tu sitio web.

Además, este target asume un único stage desplegado en el entorno con credenciales AWS. Debes ajustar el comando si despliegas múltiples stages en la misma cuenta/región.

Terraform

Para proyectos Terraform, el target load:runtime-config copia el runtime-config.json creado tras el último terraform apply local.

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 relacionada 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) e inicia servidores locales para APIs conectadas mediante el generador API Connection.

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

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 desarrollo conjunto del sitio y API sin desplegar infraestructura.

En este modo, si no hay runtime-config.json y usas Autenticación Cognito (via CloudScape Website Auth), el login se omitirá y las peticiones no incluirán headers de autenticación.

Para habilitar login 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 estándares de proyectos TypeScript. Consulta la guía de proyectos TypeScript.

Para pruebas específicas de React, React Testing Library está preinstalado. 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

El generador crea infraestructura CDK o Terraform según tu iacProvider. Úsala para desplegar tu sitio.

CDK

Recomendamos usar el generador ts#infra para crear una aplicación CDK.

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

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

Esto configura:

1. Bucket S3 para alojar archivos estáticos
2. Distribución CloudFront para entrega global
3. Web ACL WAF para protección
4. Origin Access Control para acceso seguro
5. Despliegue automático de archivos y configuración

Terraform

Recomendamos usar el generador terraform#project para crear un proyecto Terraform.

Usa el módulo generado en packages/common/terraform para desplegar:

packages/infra/src/main.tf

# Desplegar sitio web
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
}

Esto configura:

1. Bucket S3 para archivos estáticos
2. Distribución CloudFront
3. Web ACL WAF (en us-east-1)
4. Origin Access Control
5. Despliegue automático de archivos y configuración

Nota

El provider aws.us_east_1 es requerido para recursos CloudFront/WAF en us-east-1. Asegúrate de incluirlo:

packages/infra/src/providers.tf

provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}