Saltearse al contenido
@aws/nx-plugin
Blog

Sitio web de CloudScape

Este generador crea un nuevo sitio web en 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.

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 Recursos 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 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 (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 pruebas
    • tsconfig.app.json Configuración TypeScript para código fuente
    • tsconfig.spec.json Configuración TypeScript para pruebas

    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 para tu sitio web
      • Directorycore
        • static-website.ts Construct 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

    Crear una ruta/página

    Tu sitio web CloudScape incluye TanStack Router configurado. Esto facilita la adición de 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. Notarás que se generan automáticamente un Route y RouteComponent. ¡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 ...
        // 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 proporciona 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 está desplegada.

    Infraestructura

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

    Tu construct de sitio web CDK 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);
    

        // Añade automáticamente valores al RuntimeConfig
        new MyApi(this, 'MyApi');
    

        // 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 construct que añada valores al RuntimeConfig, de lo contrario no estarán presentes 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.httpApis.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 local conozca las URLs del backend, configuración de identidad, etc.

    Tu proyecto de sitio web está configurado con un target 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 target 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

    Antes de ejecutar el servidor de desarrollo local, asegúrate de haber desplegado tu infraestructura y haber cargado la configuración local.

    Luego puedes ejecutar el target serve:

    Terminal window
    pnpm nx run <my-website>:serve

    Construcción

    Puedes construir tu sitio web usando el target 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 analizar 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 lo que te recomendamos consultar 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 target test:

    Terminal window
    pnpm nx run <my-website>:test

    Desplegar tu sitio web

    Para desplegar tu sitio web, recomendamos usar el Generador de Infraestructura TypeScript para crear una aplicación CDK.

    Puedes usar el construct 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');
      }
    }