Sitio web de React

Este generador crea un nuevo sitio web en React configurado con shadcn/ui por defecto, 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.

Proveedor de UX

El uxProvider predeterminado es shadcn/ui. También puedes seleccionar Cloudscape o None (trae tu propia biblioteca de componentes).

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#website
5. Complete los parámetros requeridos
6. Haga clic en Generate

CLI

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#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#website --dry-run

yarn

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

npm

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

bun

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	El nombre de la aplicación.
framework	react	react	El framework frontend a utilizar.
directory	string	packages	El directorio de la nueva aplicación.
subDirectory	string	-	El subdirectorio en el que se coloca el proyecto. Por defecto, este es el nombre del proyecto.
ux	none | cloudscape | shadcn	shadcn	El proveedor de UX preferido.
tailwind	boolean	true	Habilitar TailwindCSS para estilos basados en utilidades.
tanstackRouter	boolean	true	Habilitar Tanstack router para enrutamiento con seguridad de tipos.
infra	cloudfront-s3 | none	cloudfront-s3	El tipo de infraestructura con la que desplegar tu sitio web.
iac	inherit | cdk | terraform	inherit	El proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establece en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instala una vez al final.

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
• Directoriosrc

  • main.tsx Punto de entrada de la aplicación con configuración de React
  • config.ts Configuración de la aplicación (ej. logo)
  • Directoriocomponents

    • AppLayout Componentes para el layout general y barra de navegación
  • Directoriohooks

    • useAppLayout.tsx Hook para ajustar el AppLayout desde componentes anidados (solo Cloudscape)
  • Directorioroutes

    • index.tsx Ruta (o página) de ejemplo para TanStack Router
  • styles.css Estilos globales
• vite.config.mts 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

Sin TanStack Router

Si optaste por no usar TanStack Router, se te proporcionará un archivo simple src/app.tsx como punto de entrada de tu aplicación en lugar del directorio routes.

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

• Directoriopackages/common/constructs

  • Directoriosrc

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

      • …
    • Directoriocore/ 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

Proyecto generado

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

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

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

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

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

Proyecto generado

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

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directoriostatic-websites

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

    • static-website.ts Construct genérico StaticWebsite

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directoriostatic-websites

      • Directorio<name>

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

    • Directoriostatic-website

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

Arquitectura

El sitio web desplegado tiene la siguiente arquitectura:

Encabezados de seguridad

La distribución de CloudFront aplica una política de encabezados de respuesta que establece Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy y una Content-Security-Policy en todas las respuestas.

Se aplica una Content-Security-Policy predeterminada. Restringe scripts y framing para mitigar XSS y clickjacking, mientras permite conexiones HTTPS y WSS para que el sitio web pueda llamar a endpoints de servicios AWS (como API Gateway, Cognito y Bedrock AgentCore) cuyas URLs solo se conocen en tiempo de despliegue. Para ajustar la política (por ejemplo, restringir connect-src a tus orígenes específicos), edita el valor content_security_policy en tu static-website.ts generado (CDK) o static-website.tf (Terraform).

runtime-config.json se sirve con Cache-Control: no-cache para que los navegadores siempre obtengan la configuración más reciente después de un redespliegue, en lugar de usar una copia en caché obsoleta.

Implementando tu sitio web React

La documentación de React es un buen punto de partida para aprender los fundamentos.

ux = cloudscape

Puedes consultar la documentación de Cloudscape para detalles sobre los componentes disponibles y su uso.

ux = shadcn

Puedes consultar la documentación de shadcn/ui para detalles sobre los componentes disponibles y su uso.

Rutas

Crear una ruta/página

Tu sitio web 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á el namespace connection de la configuración en tiempo de ejecució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, MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // El sitio web puede declararse en cualquier punto — la configuración se resuelve de forma diferida
    new MyWebsite(this, 'MyWebsite');

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

Constructo CDK de sitio web

Con CDK, el construct del sitio web puede declararse en cualquier punto de tu stack. La configuración en tiempo de ejecución se resuelve de forma diferida en tiempo de síntesis, por lo que todos los valores se incluirán independientemente del orden de declaración.

Terraform

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

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

packages/infra/src/main.tf

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Despliega la configuración en runtime-config.json automáticamente
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 para añadir a la configuración
  depends_on = [module.my_api]
}

Orden de módulos

Debes declarar tu módulo del sitio web después de cualquier módulo que añada a la configuración y configurar el depends_on apropiado para garantizar el orden, 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 en tiempo de ejecución

Para detalles sobre cómo se almacena la configuración en tiempo de ejecución en AWS AppConfig y cómo los consumidores del lado del servidor (funciones Lambda, agentes) pueden recuperarla, consulta la guía de Configuración en Tiempo de Ejecución.

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"

Nombres de etapa personalizados

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

El comando canónico para el desarrollo local es dev, que inicia tu sitio web (y cualquier servidor local para APIs que hayas conectado) con un solo comando:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

El target serve también está disponible para cuando necesites controlar cuánto de tu aplicación se ejecuta localmente versus apuntando a infraestructura AWS desplegada. Para una visión general más amplia del desarrollo local a través de proyectos conectados, incluyendo cómo se comporta dev para proyectos con múltiples componentes, consulta la guía de Desarrollo 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 de runtime local.

Puedes ejecutar este target con el siguiente comando:

pnpm

pnpm nx serve <my-website>

yarn

yarn nx serve <my-website>

npm

npx nx serve <my-website>

bun

bunx nx serve <my-website>

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

Target Dev

El target dev inicia un servidor de desarrollo local para tu sitio web (con Vite MODE establecido en local-dev), así como iniciando cualquier servidor local para APIs que hayas conectado a tu sitio web mediante el generador Connection.

Cuando tu servidor de sitio web local se ejecuta mediante este target, runtime-config.json se sobrescribe automáticamente para apuntar a las URLs de tu API que se ejecutan localmente.

Puedes ejecutar este target con el siguiente comando:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

Este target es útil cuando estás trabajando en tu sitio web y API y deseas iterar rápidamente sin desplegar tu infraestructura.

Script dev del workspace

El package.json raíz de tu workspace incluye un script dev que ejecuta el target dev para cada proyecto que tenga uno:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Esto inicia el servidor de desarrollo local para tu sitio web (y cualquier otro proyecto con un target dev) con un solo comando. Para ejecutar solo este sitio web, usa su propio target dev (por ejemplo, nx dev <my-website>).

Autenticación simulada

Cuando se ejecuta en este modo y no hay runtime-config.json presente, si has configurado Autenticación Cognito (mediante el generador ts#website#auth), el inicio de sesión se omitirá y las solicitudes a tus servidores locales no incluirán encabezados de autenticación.

Para habilitar el inicio de sesión y la autenticación para dev, despliega tu infraestructura y carga la configuración de runtime.

Comportamiento de Dev

Al ejecutar con dev, puedes especificar cualquier variable de entorno requerida por tus APIs para apuntar a otros recursos AWS desplegados, por ejemplo:

pnpm

DYNAMODB_TABLE_NAME=xxxxx pnpm nx dev <my-website>

yarn

DYNAMODB_TABLE_NAME=xxxxx yarn nx dev <my-website>

npm

DYNAMODB_TABLE_NAME=xxxxx npx nx dev <my-website>

bun

DYNAMODB_TABLE_NAME=xxxxx bunx nx dev <my-website>

Ten en cuenta que tus servidores de API locales se ejecutarán con las credenciales de AWS que hayas configurado localmente.

Construcción

Puedes construir tu sitio web usando el target build. Esto ejecuta los targets bundle, compile, test y lint, verificando tipos, empaquetando, probando y analizando tu sitio web.

pnpm

pnpm nx build <my-website>

yarn

yarn nx build <my-website>

npm

npx nx build <my-website>

bun

bunx nx build <my-website>

El target bundle usa Vite para crear un paquete de producción en el directorio raíz dist/packages/<my-website>/bundle. Este es el artefacto desplegable consumido por la infraestructura de tu sitio web. Puedes ejecutarlo por sí solo:

pnpm

pnpm nx bundle <my-website>

yarn

yarn nx bundle <my-website>

npm

npx nx bundle <my-website>

bun

bunx nx bundle <my-website>

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 test <my-website>

yarn

yarn nx test <my-website>

npm

npx nx test <my-website>

bun

bunx nx test <my-website>

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

Región del proveedor WAF

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

Conexiones

Usa el generador connection para integrar este proyecto con otros en tu workspace. Las siguientes conexiones involucran este proyecto:

React a tRPCLlama a una API tRPC desde un sitio web React

React a FastAPILlama a una API FastAPI en Python desde un sitio web React

React a Smithy APILlama a una API Smithy desde un sitio web React

React a Python AgentLlama a un Python Agent desde un sitio web React

React a TypeScript AgentLlama a un TypeScript Agent desde un sitio web React

React a AG-UI AgentLlama a un Agent que expone el protocolo AG-UI desde un sitio web React a través de CopilotKit