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

Site React

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.

Uso

Seção intitulada “Uso”

Gerar um Website React

Seção intitulada “Gerar um Website React”

Você pode gerar um novo Website React 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#react-website
  5. Preencha os parâmetros obrigatórios
    • Clique em Generate

    Opções

    Seção intitulada “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.
    enableTailwind boolean true Enable TailwindCSS for utility-first styling.
    enableTanstackRouter boolean true Enable Tanstack router for type-safe routing.

    Saída do Gerador

    Seção intitulada “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 de exemplo (ou página) 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 implantação do 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 React

    Seção intitulada “Implementando seu Website React”

    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 utilizá-los.

    Rotas

    Seção intitulada “Rotas”

    Criando uma Rota/Página

    Seção intitulada “Criando uma Rota/Página”

    Seu website CloudScape vem com TanStack Router configurado por padrão. 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!
    Seção intitulada “Navegação Entre Páginas”

    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

    Seção intitulada “Configuração de Runtime”

    A configuração da sua infraestrutura AWS CDK é fornecida ao seu website via Runtime Configuration. Isso permite que seu website acesse detalhes como URLs de API que só são conhecidos após a implantação.

    Infraestrutura

    Seção intitulada “Infraestrutura”

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

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

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

    Seção intitulada “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

    Seção intitulada “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 as 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 prefixo dos nomes de stage no arquivo src/main.ts do seu projeto de infraestrutura, precisará atualizar o target load:runtime-config no arquivo project.json do seu website de acordo.

    Além disso, é importante notar que o target load:runtime-config assume que um único stage da sua aplicação está implantado no ambiente para o qual você tem credenciais AWS. Você precisará ajustar o comando se implantar múltiplos stages na mesma conta e região.

    Servidor de Desenvolvimento Local

    Seção intitulada “Servidor de Desenvolvimento Local”

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

    Target Serve

    Seção intitulada “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 tenha 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 enquanto aponta para APIs “reais” implantadas e outras infraestruturas.

    Target Serve Local

    Seção intitulada “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 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 as 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 de Autenticação para Website CloudScape), o login será ignorado e requisições para seus 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

    Seção intitulada “Build”

    Você pode construir seu website usando o target build. Isso utiliza o Vite para criar um bundle de produção no diretório dist/packages/<my-website>/bundle, além de type-checking, compilação e linting.

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

    Testes

    Seção intitulada “Testes”

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

    Para testes específicos de React, o React Testing Library já está instalado e disponível. 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

    Seção intitulada “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');
      }
    }