Site React
Este gerador cria um novo website React com CloudScape configurado, 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.
Utilização
Seção intitulada “Utilização”Gerar um Website React
Seção intitulada “Gerar um Website React”Você pode gerar um novo Website React de duas formas:
- Instale o Nx Console VSCode Plugin se ainda não o fez
- Abra o console Nx no VSCode
- Clique em
Generate (UI)
na seção "Common Nx Commands" - Procure por
@aws/nx-plugin - ts#react-website
- Preencha os parâmetros obrigatórios
- Clique em
Generate
pnpm nx g @aws/nx-plugin:ts#react-website
yarn nx g @aws/nx-plugin:ts#react-website
npx nx g @aws/nx-plugin:ts#react-website
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 nx g @aws/nx-plugin:ts#react-website --dry-run
yarn nx g @aws/nx-plugin:ts#react-website --dry-run
npx nx g @aws/nx-plugin:ts#react-website --dry-run
bunx nx g @aws/nx-plugin:ts#react-website --dry-run
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. |
iacProvider | string | Inherit | The preferred IaC provider. By default this is inherited from your initial selection. |
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 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
Infraestrutura
Seção intitulada “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:
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
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
O gerador cria infraestrutura como código para implantar seu website baseado no iacProvider
selecionado:
Directorypackages/common/constructs/src
Directoryapp
Directorystatic-websites
- <name>.ts Infraestrutura específica para seu website
Directorycore
- static-website.ts Construct genérico StaticWebsite
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
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 usá-los.
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:
- Execute o Servidor de Desenvolvimento Local
- Crie um novo arquivo
<page-name>.tsx
emsrc/routes
, com sua posição na estrutura de arquivos representando o caminho - Observe que um
Route
eRouteComponent
são gerados automaticamente. Comece a construir sua página aqui!
Navegação Entre Páginas
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 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 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
Seção intitulada “Infraestrutura”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á a configuração de runtime como um arquivo runtime-config.json
na raiz do seu bucket S3.
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'); }}
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#trpc-api
e py#fast-api
) adicionarão automaticamente valores apropriados à configuração de runtime.
Seu módulo Terraform do website implantará a configuração de runtime como um arquivo runtime-config.json
na raiz do seu bucket S3.
# Adiciona automaticamente valores à config de runtimemodule "my_api" { source = "../../common/terraform/src/app/apis/my-api"}
# Implanta automaticamente a config de runtime em runtime-config.jsonmodule "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]}
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 config de runtime aqui const apiUrl = runtimeConfig.apis.MyApi;};
Config de Runtime Local
Seção intitulada “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 nx run <my-website>:"load:runtime-config"
yarn nx run <my-website>:"load:runtime-config"
npx nx run <my-website>:"load:runtime-config"
bunx nx run <my-website>:"load:runtime-config"
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 seguinte comando:
pnpm nx run <my-website>:serve
yarn nx run <my-website>:serve
npx nx run <my-website>:serve
bunx 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
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 via gerador API 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 nx run <my-website>:serve-local
yarn nx run <my-website>:serve-local
npx nx run <my-website>:serve-local
bunx 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 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 config de runtime.
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 type-checking, compilação e linting.
pnpm nx run <my-website>:build
yarn nx run <my-website>:build
npx nx run <my-website>:build
bunx nx run <my-website>:build
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 nx run <my-website>:test
yarn nx run <my-website>:test
npx nx run <my-website>:test
bunx nx run <my-website>:test
Implantando Seu Website
Seção intitulada “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.
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.
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:
- Um bucket S3 para hospedar arquivos estáticos do website
- Distribuição CloudFront para entrega global de conteúdo
- Web ACL WAF para proteção de segurança
- Origin Access Control para acesso seguro ao S3
- Implantação automática de arquivos do website e configuração de runtime
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.
# Implanta websitemodule "my_website" { source = "../../common/terraform/src/app/static-websites/my-website"
providers = { aws.us_east_1 = aws.us_east_1 }}
Isso configura:
- Um bucket S3 para hospedar arquivos estáticos do website
- Distribuição CloudFront para entrega global de conteúdo
- Web ACL WAF para proteção de segurança (implantado em us-east-1)
- Origin Access Control para acesso seguro ao S3
- Implantação automática de arquivos do website e configuração de runtime