Pular para o conteúdo
@aws/nx-plugin
Blog

Site CloudScape

Este gerador cria um novo website React com CloudScape configurado, junto com a infraestrutura AWS CDK para implantar seu website na nuvem como um site estático hospedado no S3, servido pelo CloudFront e protegido pelo WAF.

A aplicação gerada utiliza Vite como ferramenta de build e bundler. Ela usa TanStack Router para roteamento type-safe.

Embora este gerador configure o CloudScape, ele é fundamentalmente um gerador de projetos React, e você pode modificar seu código para migrar para um sistema de design ou biblioteca de componentes alternativo, se desejar.

Uso

Gerar um Website CloudScape

Você pode gerar um novo Website CloudScape de duas formas:

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - ts#cloudscape-website
  5. Preencha os parâmetros obrigatórios
    • Clique em Generate

    Opções

    Parâmetro Tipo Padrão Descrição
    name Obrigatório string - The name of the application.
    directory string packages The directory of the new application.

    Saída do Gerador

    O gerador criará a seguinte estrutura de projeto no diretório <directory>/<name>:

    • index.html Ponto de entrada HTML
    • public Assets estáticos
    • Directorysrc
      • main.tsx Ponto de entrada da aplicação com configuração React
      • config.ts Configuração da aplicação (ex: logo)
      • Directorycomponents
        • AppLayout Componentes para o layout CloudScape e barra de navegação
      • Directoryhooks
        • useAppLayout.tsx Hook para ajustar o AppLayout a partir de componentes aninhados
      • Directoryroutes
        • Directorywelcome
          • index.tsx Rota (ou página) de exemplo para @tanstack/react-router
      • styles.css Estilos globais
    • vite.config.ts Configuração do Vite e Vitest
    • tsconfig.json Configuração TypeScript base para código e testes
    • tsconfig.app.json Configuração TypeScript para código fonte
    • tsconfig.spec.json Configuração TypeScript para testes

    O gerador também criará código de infraestrutura CDK para implantar seu website no diretório packages/common/constructs:

    • Directorysrc
      • Directoryapp
        • Directorystatic-websites
          • <name>.ts Infraestrutura específica do seu website
      • Directorycore
        • static-website.ts Construct genérico StaticWebsite

    Implementando seu Website CloudScape

    A documentação do React é um bom ponto de partida para aprender o básico de desenvolvimento com React. Você pode consultar a documentação do CloudScape para detalhes sobre os componentes disponíveis e como usá-los.

    Rotas

    Criando uma Rota/Página

    Seu website CloudScape vem com TanStack Router configurado. Isso facilita a adição de novas rotas:

    1. Execute o Servidor de Desenvolvimento Local
    2. Crie um novo arquivo <nome-da-pagina>.tsx em src/routes, onde a posição na estrutura de arquivos representa o caminho
    3. Observe que um Route e RouteComponent são gerados automaticamente. Você pode começar a construir sua página aqui!

    Você pode usar o componente Link ou o 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 ...
        // Use `navigate` para redirecionar após uma ação assíncrona
        navigate({ to: '/products/$id', { params: { id }} });
      };
    

      return (
        <>
          <Link to="/products">Cancelar</Link>
          <Button onClick={submit}>Enviar</Button>
        </>
      )
    };

    Para mais detalhes, consulte a documentação do TanStack Router.

    Configuração de Runtime

    Configurações da sua infraestrutura AWS CDK são fornecidas ao seu website via Configuração de Runtime. Isso permite que seu website acesse detalhes como URLs de API que só são conhecidos após a implantação.

    Infraestrutura

    O construct CDK RuntimeConfig pode ser usado para adicionar e recuperar configurações na sua infraestrutura CDK. Os constructs CDK gerados por @aws/nx-plugin (como APIs tRPC e FastAPIs) adicionarão automaticamente valores apropriados ao RuntimeConfig.

    Seu construct de website CDK implantará a configuração de runtime como um arquivo runtime-config.json na raiz do seu 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);
    

        // Adiciona automaticamente valores ao RuntimeConfig
        new MyApi(this, 'MyApi');
    

        // Implanta automaticamente a configuração em runtime-config.json
        new MyWebsite(this, 'MyWebsite');
      }
    }

    Você deve declarar seu website após quaisquer constructs que adicionem ao RuntimeConfig, caso contrário eles estarão faltando no arquivo runtime-config.json.

    Código do Website

    No seu website, você pode usar o hook useRuntimeConfig para recuperar valores da configuração de runtime:

    import { useRuntimeConfig } from '../hooks/useRuntimeConfig';
    

    const MyComponent = () => {
      const runtimeConfig = useRuntimeConfig();
    

      // Acesse valores da configuração de runtime aqui
      const apiUrl = runtimeConfig.httpApis.MyApi;
    };

    Configuração de Runtime Local

    Ao executar o servidor de desenvolvimento local, você precisará de um arquivo runtime-config.json no diretório public para que seu website local conheça URLs de backend, configuração de identidade, etc.

    Seu projeto de website está configurado com um target load:runtime-config que você pode usar para baixar o arquivo runtime-config.json de uma aplicação implantada:

    Terminal window
    pnpm nx run <my-website>:"load:runtime-config"

    Se você alterar o nome do seu stack no src/main.ts do projeto de infraestrutura, precisará atualizar o target load:runtime-config no arquivo project.json do seu website com o nome do stack a ser carregado.

    Servidor de Desenvolvimento Local

    Antes de executar o servidor de desenvolvimento local, certifique-se de ter implantado sua infraestrutura e carregado a configuração de runtime local.

    Você pode então executar o target serve:

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

    Build

    Você pode construir seu website usando o target build. Isso usa o Vite para criar um bundle de produção no diretório dist/packages/<my-website>/bundle, além de verificar tipos, compilar e lintar seu website.

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

    Testes

    Testar seu website é similar a escrever testes em um projeto TypeScript padrão. Consulte o guia de projetos TypeScript para detalhes.

    Para testes específicos de React, o React Testing Library já está instalado e disponível para escrever testes. Para detalhes de uso, consulte a documentação do React Testing Library.

    Você pode executar seus testes usando o target test:

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

    Implantando Seu Website

    Para implantar seu website, recomendamos usar o Gerador de Infraestrutura TypeScript para criar uma aplicação CDK.

    Você pode usar o construct CDK gerado em packages/common/constructs para implantar seu website.

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