Site React

Este gerador cria um novo site em React com CloudScape configurado, juntamente com a infraestrutura AWS CDK para implantar seu site 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.

Nota

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 Site React

Você pode gerar um novo Site React de duas formas:

VSCode

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
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website

yarn

yarn nx g @aws/nx-plugin:ts#react-website

npm

npx nx g @aws/nx-plugin:ts#react-website

bun

bunx nx g @aws/nx-plugin:ts#react-website

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#react-website --dry-run

npm

npx nx g @aws/nx-plugin:ts#react-website --dry-run

bun

bunx nx g @aws/nx-plugin:ts#react-website --dry-run

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

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 base do TypeScript 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 site no diretório packages/common/constructs:

• Directorysrc

  • Directoryapp

    • Directorystatic-websites

      • <name>.ts Infraestrutura específica do seu site
  • Directorycore

    • static-website.ts Construct genérico StaticWebsite

Implementando Seu Site React

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 site 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!

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

A configuração da sua infraestrutura AWS CDK é fornecida ao seu site via Runtime Configuration. Isso permite que seu site 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ção em sua infraestrutura CDK. Os constructs CDK gerados por @aws/nx-plugin (como APIs tRPC e FastAPIs) adicionarão automaticamente valores ao RuntimeConfig.

Seu construct CDK de site 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 Site

Em seu site, 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 config 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 site local conheça URLs de backend, configuração de identidade, etc.

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

pnpm

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

yarn

yarn nx run <my-website>:"load:runtime-config"

npm

npx nx run <my-website>:"load:runtime-config"

bun

bunx nx run <my-website>:"load:runtime-config"

Se você alterar o nome da sua stack no src/main.ts do projeto de infraestrutura, precisará atualizar o target load:runtime-config no arquivo project.json do seu site com o nome da stack para carregar a configuração.

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 site. Este target requer que você tenha implantado qualquer infraestrutura de suporte com a qual o site interage, e ter carregado a configuração de runtime local.

Você pode executar este target com o comando:

pnpm

pnpm nx run <my-website>:serve

yarn

yarn nx run <my-website>:serve

npm

npx nx run <my-website>:serve

bun

bunx nx run <my-website>:serve

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

Target Serve Local

O target serve-local inicia um servidor de desenvolvimento local para seu site (com MODE do Vite definido como serve-local), além de iniciar servidores locais para quaisquer APIs conectadas ao seu site 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:

pnpm

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

yarn

yarn nx run <my-website>:serve-local

npm

npx nx run <my-website>:serve-local

bun

bunx nx run <my-website>:serve-local

Este target é útil quando você está trabalhando simultaneamente no site 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 Site CloudScape), 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 fazer o build do seu site 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 type-checking, compilação e linting.

pnpm

pnpm nx run <my-website>:build

yarn

yarn nx run <my-website>:build

npm

npx nx run <my-website>:build

bun

bunx nx run <my-website>:build

Testes

Testar seu site é similar a escrever testes em um projeto TypeScript padrão. Consulte o guia de projeto TypeScript para 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:

pnpm

pnpm nx run <my-website>:test

yarn

yarn nx run <my-website>:test

npm

npx nx run <my-website>:test

bun

bunx nx run <my-website>:test

Implantando Seu Site

Para implantar seu site, 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 site.

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