Sitio web de CloudScape

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 empaquetador. Emplea TanStack Router para enrutamiento con verificación de tipos.

Uso

Generar un sitio web con CloudScape

Puedes generar un nuevo sitio web con CloudScape de dos formas:

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#cloudscape-website
Complete los parámetros requeridos
Haga clic en 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

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

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	The name of the application.
directory	string	packages	The directory of the new application.

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 diseño general de CloudScape y barra de navegación
- Directoryhooks
  - useAppLayout.tsx Hook para ajustar el AppLayout desde componentes anidados
- Directoryroutes
  - Directorywelcome
    index.tsx Ruta de ejemplo (o página) 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 de TypeScript para código fuente
tsconfig.spec.json Configuración de 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 Constructo genérico StaticWebsite

Implementando tu sitio web con CloudScape

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

Creando una ruta/página

Tu sitio web CloudScape incluye TanStack Router configurado. Esto facilita agregar nuevas rutas:

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

Navegación 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 ...
    // Usa `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 API que no se conocen hasta que la aplicación es desplegada.

Infraestructura

El constructo CDK RuntimeConfig puede usarse para agregar y recuperar configuración en tu infraestructura CDK. Los constructos CDK generados por @aws/nx-plugin (como APIs tRPC y FastAPIs) agregará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);

    // Agrega 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 agregue valores 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 web local conozca las URLs del backend, configuración de identidad, etc.

Tu proyecto de sitio web está configurado con un objetivo load:runtime-config que puedes usar para descargar el archivo runtime-config.json desde 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 nombre de tu stack en el archivo src/main.ts de tu proyecto de infraestructura, deberás actualizar el objetivo load:runtime-config en el archivo project.json de tu sitio web con el nombre del stack del cual cargar la configuración.

Servidor de desarrollo local

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

Objetivo Serve

El objetivo serve inicia un servidor de desarrollo local para tu sitio web. Este objetivo 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 objetivo 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 objetivo es útil para trabajar en cambios del sitio web apuntando a APIs “reales” desplegadas y otra infraestructura.

Objetivo Serve Local

El objetivo 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 de API.

Cuando el servidor local del sitio web se ejecuta mediante este objetivo, runtime-config.json se sobrescribe automáticamente para apuntar a las URLs de API locales.

Puedes ejecutar este objetivo 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 objetivo es útil cuando trabajas simultáneamente en tu sitio web y API, y deseas iterar rápidamente sin desplegar la infraestructura.

Al ejecutarse en este modo y si 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 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 objetivo build. Esto utiliza Vite para crear un paquete de producción en el directorio raíz dist/packages/<my-website>/bundle, además de verificar tipos, compilar y realizar 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 pruebas 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 pruebas usando el objetivo 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');
  }
}