Guia de Início Rápido

Este guia explica o básico da instalação e uso do @aws/nx-plugin para construir projetos rapidamente na AWS.

Dica

Para um tutorial mais detalhado sobre como construir uma aplicação full-stack, confira o Tutorial de Aventura no Calabouço.

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
• PNPM >= 10 (também pode usar Yarn >= 4, Bun >= 1 ou NPM >= 10 se preferir)
  • verifique executando pnpm --version, yarn --version, bun --version ou npm --version
• UV >= 0.5.29
  1. instale Python 3.12 executando: uv python install 3.12.0
  2. verifique com uv python list --only-installed
• Credenciais AWS configuradas para sua conta AWS de destino (onde seu aplicativo será implantado)
• Se estiver usando VSCode, recomendamos instalar o Nx Console VSCode Plugin.

Dica

Se você usa um Assistente de IA como Amazon Q Developer, Cursor, Claude Code ou Cline, pode querer também instalar o Nx Plugin para AWS MCP server.

Passo 1: Inicializar um Novo Workspace Nx

Execute o seguinte comando para criar um workspace Nx com o gerenciador de pacotes de sua escolha:

pnpm

npx create-nx-workspace@~21.0.3 my-project --pm=pnpm --preset=@aws/nx-plugin --ci=skip

yarn

npx create-nx-workspace@~21.0.3 my-project --pm=yarn --preset=@aws/nx-plugin --ci=skip

npm

npx create-nx-workspace@~21.0.3 my-project --pm=npm --preset=@aws/nx-plugin --ci=skip

bun

npx create-nx-workspace@~21.0.3 my-project --pm=bun --preset=@aws/nx-plugin --ci=skip

Após a conclusão, navegue até o diretório do projeto:

cd my-project

Passo 2: Usar Geradores para Estruturar seu Projeto

Vamos adicionar uma API tRPC, Site React, Autenticação Cognito e Infraestrutura CDK neste guia rápido. Dependendo do tipo de projeto que você está construindo, você pode escolher qualquer combinação de geradores para inicializar rapidamente seu projeto. Confira os Guias na barra de navegação à esquerda para ver a lista completa de opções.

Adicionar uma API tRPC

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#trpc-api
5. Preencha os parâmetros obrigatórios
   • name: demo-api
   • auth: IAM
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

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

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

Isso criará a API dentro da pasta packages/demo-api.

Adicionar um Site React

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
   • name: demo-website
6. Clique em Generate

CLI

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#react-website --name=demo-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 --name=demo-website --dry-run

yarn

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

npm

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

bun

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

Isso estrutura um novo site React em packages/demo-website.

Adicionar Autenticação Cognito

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#auth
5. Preencha os parâmetros obrigatórios
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

yarn

yarn nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

npm

npx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

bun

bunx nx g @aws/nx-plugin:ts#react-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

pnpm nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

npm

npx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

bun

bunx nx g @aws/nx-plugin:ts#react-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 site.

Conectar Frontend ao Backend

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 - api-connection
5. Preencha os parâmetros obrigatórios
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

yarn

yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

npm

npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

bun

bunx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

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

pnpm

pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

yarn

yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

npm

npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

bun

bunx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

Isso configura os provedores necessários para garantir que seu site possa chamar sua API tRPC.

Adicionar Infraestrutura CDK

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#infra
5. Preencha os parâmetros obrigatórios
   • name: infra
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra

bun

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

pnpm nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

bun

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 3: Executar seu Site e API Localmente

Use o seguinte comando para iniciar servidores locais de desenvolvimento para seu site e APIs conectadas:

pnpm

pnpm nx run demo-website:serve-local

yarn

yarn nx run demo-website:serve-local

npm

npx nx run demo-website:serve-local

bun

bunx nx run demo-website:serve-local

Seu site estará disponível em http://localhost:4200.

Alterações tanto no seu site quanto na API serão refletidas em tempo real, pois ambos os servidores locais recarregarão automaticamente.

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', {
      integrations: DemoApi.defaultIntegrations(this).build(),
    });
    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new DemoWebsite(this, 'website');
  }
}

Este é todo o código CDK necessário para implantar nossa aplicação full-stack.

Construir e Implantar a Infraestrutura

Em seguida, execute o seguinte comando para construir seu projeto:

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Dica

Se encontrar erros de lint, você pode executar o seguinte comando para corrigi-los automaticamente.

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

Execute o seguinte comando para implantar seu projeto:

pnpm

pnpm nx run infra:deploy --all

yarn

yarn nx run infra:deploy --all

npm

npx nx run infra:deploy --all

bun

bunx nx run infra:deploy --all

Dica

Você precisará garantir que seu ambiente AWS foi adequadamente inicializado para o CDK.

A inicialização do CDK é necessária tanto para sua região AWS de implantação quanto para us-east-1 para permitir a implantação do WebACL AWS WAF para o site.

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Passo 5: Testar o Site com Recursos Cloud Implantados

1. Obtenha o arquivo runtime-config.json:

   pnpm

   pnpm nx run demo-website:load:runtime-config

   yarn

   yarn nx run demo-website:load:runtime-config

   npm

   npx nx run demo-website:load:runtime-config

   bun

   bunx nx run demo-website:load:runtime-config

2. Inicie o servidor local do site

   pnpm

   pnpm nx run demo-website:serve

   yarn

   yarn nx run demo-website:serve

   npm

   npx nx run demo-website:serve

   bun

   bunx nx run demo-website:serve

Seu site estará disponível em http://localhost:4200 e apontará para os recursos implantados da API e autenticação.

---

Parabéns! 🎉 Você implantou com sucesso uma aplicação full-stack usando @aws/nx-plugin!