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

Site CloudScape

Este gerador cria um novo website React com CloudScape configurado, juntamente 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 empacotador. Ela usa TanStack Router para roteamento type-safe.

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 os fundamentos 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 <page-name>.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

    A configuração de sua infraestrutura AWS CDK é fornecida 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 da aplicação.

    Infraestrutura

    O construct CDK RuntimeConfig pode ser usado para adicionar e recuperar configuração em 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', {
          integrations: MyApi.defaultIntegrations(this).build(),
        });
    

        // Implanta automaticamente a config de runtime em runtime-config.json
        new MyWebsite(this, 'MyWebsite');
      }
    }

    Você deve garantir que declara 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

    Em 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.apis.MyApi;
    };

    Configuração de Runtime Local

    Ao executar o servidor de desenvolvimento local, você precisará de um arquivo runtime-config.json em seu 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 para carregar a configuração de runtime.

    Servidor de Desenvolvimento Local

    Você pode executar um servidor de desenvolvimento local usando os targets serve ou serve-local.

    Target Serve

    O target serve inicia um servidor de desenvolvimento local para seu website. Este target requer que você tenha implantado qualquer infraestrutura de suporte com a qual o website interage, e ter carregado a configuração de runtime local.

    Você pode executar este target com o comando:

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

    Este target é útil para trabalhar em alterações do website apontando para APIs “reais” implantadas e outras infraestruturas.

    Target Serve Local

    O target serve-local inicia um servidor de desenvolvimento local para seu website (com Vite MODE definido como serve-local), além de iniciar quaisquer servidores locais para APIs conectadas ao seu website via gerador de Conexão de API.

    Quando seu servidor local é executado via este target, o runtime-config.json é automaticamente sobrescrito para apontar para URLs de API locais.

    Você pode executar este target com o comando:

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

    Este target é útil quando você está trabalhando simultaneamente no website e na API e deseja iterar rapidamente sem implantar a infraestrutura.

    Quando executado neste modo e nenhum runtime-config.json estiver presente, se você configurou Autenticação Cognito (via gerador CloudScape Website Auth), o login será ignorado e requisições para servidores locais não incluirão headers de autenticação.

    Para habilitar login e autenticação no serve-local, implante sua infraestrutura e carregue a configuração de runtime.

    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 mais 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 para você 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');
      }
    }