Guia de Início Rápido
Este guia orienta você pelos fundamentos de instalação e uso do @aws/nx-plugin
para construir projetos rapidamente na AWS.
Pré-requisitos
As seguintes dependências globais são necessárias antes de prosseguir:
- Git
- Node >= 22 (Recomendamos usar algo como NVM para gerenciar versões do Node)
- verifique executando
node --version
- verifique executando
- PNPM >= 10 (também pode usar Yarn >= 4, Bun >= 1 ou NPM >= 10 se preferir)
- verifique executando
pnpm --version
,yarn --version
,bun --version
ounpm --version
- verifique executando
- UV >= 0.5.29
- instale Python 3.12 executando:
uv python install 3.12.0
- verifique com
uv python list --only-installed
- instale Python 3.12 executando:
- Credenciais da AWS configuradas para a sua conta AWS de destino (onde sua aplicação será implantada)
- Se estiver usando VSCode, recomendamos instalar o Nx Console VSCode Plugin.
Passo 1: Inicializar um Novo Workspace Nx
Execute o seguinte comando para criar um workspace Nx com o gerenciador de pacotes de sua escolha:
npx create-nx-workspace@~20.6.3 my-project --pm=pnpm --preset=ts --ci=skip --formatter=prettier
npx create-nx-workspace@~20.6.3 my-project --pm=yarn --preset=ts --ci=skip --formatter=prettier
npx create-nx-workspace@~20.6.3 my-project --pm=npm --preset=ts --ci=skip --formatter=prettier
npx create-nx-workspace@~20.6.3 my-project --pm=bun --preset=ts --ci=skip --formatter=prettier
Após a conclusão, navegue até o diretório do projeto:
cd my-project
Passo 2: Adicionar o Plugin Nx para AWS
Instale o plugin com:
pnpm add -Dw @aws/nx-plugin
yarn add -D @aws/nx-plugin
npm install --legacy-peer-deps -D @aws/nx-plugin
bun install -D @aws/nx-plugin
Passo 3: Usar Geradores para Estruturar seu Projeto
Adicionaremos uma API tRPC, Website React, Autenticação Cognito e Infraestrutura CDK neste guia rápido. Dependendo do tipo de projeto, você pode escolher qualquer combinação de geradores para inicializar seu projeto rapidamente. Confira os Guias na barra de navegação à esquerda para ver a lista completa de opções.
Adicionar uma API tRPC
- 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#trpc-api
- Preencha os parâmetros obrigatórios
- apiName: demo-api
- Clique em
Generate
pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api
yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api
npx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api
bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api
Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados
pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --dry-run
yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --dry-run
npx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --dry-run
bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --dry-run
Isso criará a API na pasta packages/demo-api
.
Adicionar um Website React
- 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#cloudscape-website
- Preencha os parâmetros obrigatórios
- name: demo-website
- Clique em
Generate
pnpm nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website
yarn nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website
npx nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website
bunx nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website
Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados
pnpm nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run
yarn nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run
npx nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run
bunx nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run
Isso gera um novo website React em packages/demo-website
.
Adicionar Autenticação Cognito
- 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#cloudscape-website#auth
- Preencha os parâmetros obrigatórios
- project: @my-project/demo-website
- cognitoDomain: my-demo
- Clique em
Generate
pnpm nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
yarn nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
npx nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
bunx nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados
pnpm nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
yarn nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
npx nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
bunx nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
Isso configura a infraestrutura necessária e o código React para adicionar Autenticação Cognito ao seu website.
Conectar Frontend ao Backend
- 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 - api-connection
- Preencha os parâmetros obrigatórios
- sourceProject: @my-project/demo-website
- targetProject: @my-project/demo-api-backend
- Clique em
Generate
pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend
yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend
npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend
bunx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend
Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados
pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend --dry-run
yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend --dry-run
npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend --dry-run
bunx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend --dry-run
Isso configura os provedores necessários para garantir que seu website possa chamar sua API tRPC.
Adicionar Infraestrutura CDK
- 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#infra
- Preencha os parâmetros obrigatórios
- name: infra
- Clique em
Generate
pnpm nx g @aws/nx-plugin:ts#infra --name=infra
yarn nx g @aws/nx-plugin:ts#infra --name=infra
npx nx g @aws/nx-plugin:ts#infra --name=infra
bunx nx g @aws/nx-plugin:ts#infra --name=infra
Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados
pnpm nx g @aws/nx-plugin:ts#infra --name=infra --dry-run
yarn nx g @aws/nx-plugin:ts#infra --name=infra --dry-run
npx nx g @aws/nx-plugin:ts#infra --name=infra --dry-run
bunx nx g @aws/nx-plugin:ts#infra --name=infra --dry-run
Isso configura uma Aplicação CDK que você pode usar para implantar sua infraestrutura na AWS.
Passo 4: Definir Recursos Cloud e Implantar na AWS
Abra packages/infra/src/stacks/application-stack.ts
e adicione o seguinte código:
import * as cdk from 'aws-cdk-lib';import { DemoApi, DemoWebsite, UserIdentity } from ':my-project/common-constructs';import { Construct } from 'constructs';
export class ApplicationStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props);
const identity = new UserIdentity(this, 'identity'); const api = new DemoApi(this, 'api'); api.grantInvokeAccess(identity.identityPool.authenticatedRole);
new DemoWebsite(this, 'website'); }}
Este é todo o código CDK necessário para implantar nossa aplicação full-stack.
Compilar e Implantar a Infraestrutura
Em seguida, execute o seguinte comando para compilar seu projeto:
pnpm nx run-many --target build --all
yarn nx run-many --target build --all
npx nx run-many --target build --all
bunx nx run-many --target build --all
Passo 5: Executar o Frontend Localmente
-
Obter o arquivo
runtime-config.json
:Terminal window pnpm nx run @demo/demo-website:load:runtime-configTerminal window yarn nx run @demo/demo-website:load:runtime-configTerminal window npx nx run @demo/demo-website:load:runtime-configTerminal window bunx nx run @demo/demo-website:load:runtime-config -
Iniciar o servidor local do website
Terminal window pnpm nx run @demo/demo-website:serveTerminal window yarn nx run @demo/demo-website:serveTerminal window npx nx run @demo/demo-website:serveTerminal window bunx nx run @demo/demo-website:serve
Seu website estará disponível em http://localhost:4200
.
Parabéns! 🎉 Você implantou com sucesso uma aplicação full-stack usando @aws/nx-plugin
!