Site React

Este gerador cria um novo website React com shadcn/ui configurado por padrão, juntamente com a infraestrutura AWS CDK ou Terraform 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. Usa TanStack Router para roteamento type-safe.

Provedor UX

O uxProvider padrão é shadcn/ui. Você também pode selecionar Cloudscape ou None (traga sua própria biblioteca de componentes).

Utilização

Gerar um Website React

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	O nome da aplicação.
framework	react	react	O framework frontend a ser usado.
directory	string	packages	O diretório da nova aplicação.
subDirectory	string	-	O subdiretório onde o projeto é colocado. Por padrão, este é o nome do projeto.
ux	none | cloudscape | shadcn	shadcn	O provedor de UX preferido.
tailwind	boolean	true	Ativar TailwindCSS para estilização utility-first.
tanstackRouter	boolean	true	Ativar roteador Tanstack para roteamento type-safe.
infra	cloudfront-s3 | none	cloudfront-s3	O tipo de infraestrutura para implantar seu website.
iac	inherit | cdk | terraform	inherit	O provedor de IaC preferido. Por padrão, este é herdado da sua seleção inicial.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

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 geral e barra de navegação
  • Directoryhooks

    • useAppLayout.tsx Hook para ajustar o AppLayout de componentes aninhados (somente Cloudscape)
  • Directoryroutes

    • index.tsx Rota de exemplo (ou página) para TanStack Router
  • styles.css Estilos globais
• vite.config.mts 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

Sem TanStack Router

Se você optou por não usar o TanStack Router, você receberá um arquivo simples src/app.tsx como ponto de entrada da aplicação em vez do diretório routes.

Infraestrutura

Como este gerador fornece infraestrutura como código com base no iacProvider escolhido, ele criará um projeto em packages/common que inclui os constructs CDK ou módulos Terraform relevantes.

O projeto comum de infraestrutura como código está estruturado da seguinte forma:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Constructs genéricos reutilizados pelos constructs em app

      • …
    • index.ts Ponto de entrada exportando os constructs de app
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador ts#project e portanto configura as mesmas metas de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos Terraform para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Módulos genéricos reutilizados pelos módulos em app

      • …
  • project.json Metas de build e configuração do projeto

Projeto gerado

Este projeto é gerado usando o gerador terraform#project e portanto configura as mesmas metas de build.

O gerador cria infraestrutura como código para implantar seu website baseado no iacProvider selecionado:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorystatic-websites

      • <name>.ts Infraestrutura específica para seu website
  • Directorycore

    • static-website.ts Construct genérico StaticWebsite

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorystatic-websites

      • Directory<name>

        • <name>.tf Módulo específico para seu website
  • Directorycore

    • Directorystatic-website

      • static-website.tf Módulo genérico de website estático

Arquitetura

O website implantado possui a seguinte arquitetura:

Cabeçalhos de Segurança

A distribuição CloudFront aplica uma política de cabeçalhos de resposta que define Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy e um Content-Security-Policy em todas as respostas.

Um Content-Security-Policy padrão é aplicado. Ele restringe scripts e framing para mitigar XSS e clickjacking, enquanto permite conexões HTTPS e WSS para que o website possa chamar endpoints de serviços AWS (como API Gateway, Cognito e Bedrock AgentCore) cujas URLs são conhecidas apenas no momento da implantação. Para ajustar a política (por exemplo, para restringir connect-src às suas origens específicas), edite o valor content_security_policy no seu static-website.ts (CDK) ou static-website.tf (Terraform) gerado.

runtime-config.json é servido com Cache-Control: no-cache para que os navegadores sempre busquem a configuração mais recente após uma reimplantação, em vez de usar uma cópia em cache desatualizada.

Implementando seu Website React

A documentação do React é um bom ponto de partida para aprender os fundamentos de desenvolvimento com React.

ux = cloudscape

Você pode consultar a documentação do Cloudscape para detalhes sobre os componentes disponíveis e como usá-los.

ux = shadcn

Você pode consultar a documentação do shadcn/ui para detalhes sobre os componentes disponíveis e como usá-los.

Rotas

Criando uma Rota/Página

Seu website 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, com sua posição na estrutura de arquivos representando o caminho
3. Observe que um Route e RouteComponent são gerados automaticamente. Comece 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 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 é 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.

Infraestrutura

CDK

O construct CDK RuntimeConfig pode ser usado para adicionar e recuperar configuração em sua infraestrutura CDK. Os constructs CDK gerados pelos geradores @aws/nx-plugin (como ts#trpc-api e py#fast-api) adicionarão automaticamente valores apropriados ao RuntimeConfig.

Seu construct CDK do website implantará o namespace connection da 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, MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // Website pode ser declarado em qualquer ponto — config de runtime é resolvida preguiçosamente
    new MyWebsite(this, 'MyWebsite');

    // Adiciona automaticamente valores ao RuntimeConfig
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Construto CDK de website

Com CDK, o construct do website pode ser declarado em qualquer ponto da sua stack. A configuração de runtime é resolvida preguiçosamente no momento do synth, então todos os valores serão incluídos independentemente da ordem de declaração.

Terraform

Com Terraform, a configuração de runtime é gerenciada através dos módulos runtime-config. Os módulos Terraform gerados pelos geradores @aws/nx-plugin (como ts#api e py#api) adicionarão automaticamente valores apropriados à configuração de runtime.

Seu módulo Terraform do website implantará o namespace connection da configuração de runtime como um arquivo runtime-config.json na raiz do seu bucket S3.

packages/infra/src/main.tf

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Adiciona automaticamente valores à config de runtime
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Implanta automaticamente a config de runtime em runtime-config.json
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # Garante que API é implantada primeiro para adicionar à config de runtime
  depends_on = [module.my_api]
}

Ordem dos módulos

Você deve garantir que declare seu módulo de website após quaisquer módulos que adicionem à configuração de runtime e configure o depends_on apropriado para garantir ordem, 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 config de runtime aqui
  const apiUrl = runtimeConfig.apis.MyApi;
};

Configuração em tempo de execução

Para detalhes sobre como a configuração de runtime é armazenada no AWS AppConfig e como consumidores server-side (funções Lambda, agentes) podem recuperá-la, consulte o guia de Configuração de Runtime.

Config 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:

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"

Nomes de estágio personalizados

CDK

Se você alterar o prefixo dos nomes de stage em src/main.ts de seu projeto de infraestrutura, precisará atualizar o target load:runtime-config no arquivo project.json de seu website.

Além disso, é importante notar que o target load:runtime-config assume que um único stage de 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.

Terraform

Para projetos Terraform, o target load:runtime-config copia o arquivo runtime-config.json criado após seu último terraform apply local.

Servidor de Desenvolvimento Local

O comando canônico para desenvolvimento local é dev, que inicia seu website (e quaisquer servidores locais para APIs que você conectou a ele) com um único comando:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

O target serve também está disponível para quando você precisa controlar quanto de sua aplicação é executado localmente versus apontando para infraestrutura AWS implantada. Para uma visão geral mais ampla do desenvolvimento local em projetos conectados, incluindo como dev se comporta para projetos com múltiplos componentes, consulte o guia Desenvolvimento 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 tenha carregado a configuração de runtime local.

Você pode executar este target com o seguinte comando:

pnpm

pnpm nx serve <my-website>

yarn

yarn nx serve <my-website>

npm

npx nx serve <my-website>

bun

bunx nx serve <my-website>

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

Target Dev

O target dev inicia um servidor de desenvolvimento local para seu website (com Vite MODE definido como local-dev), além de iniciar quaisquer servidores locais para APIs que você conectou ao seu website via gerador Connection.

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

Você pode executar este target com o seguinte comando:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

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

Script dev do Workspace

O package.json raiz do seu workspace inclui um script dev que executa o target dev para cada projeto que possui um:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Isso inicia o servidor de desenvolvimento local para seu website (e quaisquer outros projetos com um target dev) em um único comando. Para executar apenas este website, use seu próprio target dev (por exemplo, nx dev <my-website>).

Autenticação simulada

Quando executado neste modo e nenhum runtime-config.json estiver presente, se você configurou Autenticação Cognito (via gerador ts#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 para dev, implante sua infraestrutura e carregue a config de runtime.

Comportamento do Dev

Ao executar com dev, você pode especificar quaisquer variáveis de ambiente necessárias para suas APIs apontarem para outros recursos AWS implantados, por exemplo:

pnpm

DYNAMODB_TABLE_NAME=xxxxx pnpm nx dev <my-website>

yarn

DYNAMODB_TABLE_NAME=xxxxx yarn nx dev <my-website>

npm

DYNAMODB_TABLE_NAME=xxxxx npx nx dev <my-website>

bun

DYNAMODB_TABLE_NAME=xxxxx bunx nx dev <my-website>

Note que seus servidores de API locais serão executados com as credenciais AWS que você configurou localmente.

Build

Você pode construir seu website usando o target build. Isso executa os targets bundle, compile, test e lint, realizando type-checking, bundling, testes e linting do seu website.

pnpm

pnpm nx build <my-website>

yarn

yarn nx build <my-website>

npm

npx nx build <my-website>

bun

bunx nx build <my-website>

O target bundle usa o Vite para criar um bundle de produção no diretório raiz dist/packages/<my-website>/bundle. Este é o artefato implantável consumido pela infraestrutura do seu website. Você pode executá-lo separadamente:

pnpm

pnpm nx bundle <my-website>

yarn

yarn nx bundle <my-website>

npm

npx nx bundle <my-website>

bun

bunx nx bundle <my-website>

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 detalhes de uso, consulte a documentação do React Testing Library.

Você pode executar seus testes usando o target test:

pnpm

pnpm nx test <my-website>

yarn

yarn nx test <my-website>

npm

npx nx test <my-website>

bun

bunx nx test <my-website>

Implantando Seu Website

O gerador de website React cria infraestrutura como código CDK ou Terraform baseado no iacProvider selecionado. Você pode usar isso para implantar seu website.

CDK

Para implantar seu website, recomendamos usar o gerador ts#infra 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');
  }
}

Isso configura:

1. Um bucket S3 para hospedar arquivos estáticos do website
2. Distribuição CloudFront para entrega global de conteúdo
3. Web ACL WAF para proteção de segurança
4. Origin Access Control para acesso seguro ao S3
5. Implantação automática de arquivos do website e configuração de runtime

Terraform

Para implantar seu website, recomendamos usar o gerador terraform#project para criar um projeto Terraform.

Você pode usar o módulo Terraform gerado em packages/common/terraform para implantar seu website.

packages/infra/src/main.tf

# Implanta website
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
}

Isso configura:

1. Um bucket S3 para hospedar arquivos estáticos do website
2. Distribuição CloudFront para entrega global de conteúdo
3. Web ACL WAF para proteção de segurança (implantado em us-east-1)
4. Origin Access Control para acesso seguro ao S3
5. Implantação automática de arquivos do website e configuração de runtime

Região do provedor WAF

O provider aws.us_east_1 é necessário para recursos CloudFront e WAF, que devem ser implantados na região us-east-1. Garanta que sua configuração Terraform inclua este provider:

packages/infra/src/providers.tf

provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

Conexões

Use o gerador connection para integrar este projeto com outros em seu workspace. As seguintes conexões envolvem este projeto:

React para tRPCChame uma API tRPC de um site React

React para FastAPIChame uma API FastAPI Python de um site React

React para API SmithyChame uma API Smithy de um site React

React para Python AgentChame um Python Agent de um site React

React para TypeScript AgentChame um TypeScript Agent de um site React

React para AG-UI AgentChame um Agent que expõe o protocolo AG-UI de um site React via CopilotKit