Saltearse al contenido
@aws/nx-plugin
Blog

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:

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

    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:

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

    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.

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

        // 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:

    Terminal window
    pnpm 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:

    Terminal window
    pnpm 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:

    Terminal window
    pnpm 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.

    Terminal window
    pnpm 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:

    Terminal window
    pnpm 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.

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