Guia de Início Rápido

Este guia orienta você pelos conceitos básicos 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:

Obrigatório

• Git
• Node >= 22 (Recomendamos usar algo como NVM para gerenciar suas versões do node)
  • verifique executando node --version
• UV >= 0.5.29
  1. instale o Python 3.14 executando: uv python install 3.14
  2. verifique com uv python list --only-installed

Recomendado

• PNPM >= 11 (você também pode usar Yarn >= 4, Bun >= 1, ou NPM >= 11 se preferir)
  • verifique executando pnpm --version, yarn --version, bun --version ou npm --version
• AWS Credentials configuradas para sua conta AWS de destino são necessárias para implantar sua aplicação (assim como para alguns fluxos de trabalho de desenvolvimento local).
• Docker ou Finch >= 1.6.0 é necessário para alguns geradores. Para Docker, multi-platform builds devem estar configurados; Finch suporta multi-platform builds nativamente.
• Terraform >= 1.12 é necessário se você escolher usar isso para infraestrutura como código em vez de CDK
  • verifique executando terraform --version
• Se você está usando VSCode, recomendamos instalar o Nx Console VSCode Plugin.

Passo 1: Criar um Workspace

Crie um workspace Nx com o gerenciador de pacotes de sua escolha e abra o diretório que ele cria:

Crie seu workspace@aws/nx-workspace

pnpm

$ pnpm create @aws/nx-workspace my-project

yarn

$ yarn create @aws/nx-workspace my-project

npm

$ npm create @aws/nx-workspace -- my-project

bun

$ bun create @aws/nx-workspace my-project

Monte seu comando3

workspaceObrigatório

iac

cdkterraform

containers

inferdockerfinch

cd my-project

Você será solicitado a escolher seu provedor de infraestrutura como código, seja CDK ou Terraform.

Passo 2: Construir Sua Aplicação

Vamos construir uma aplicação full-stack: uma API tRPC, um website React, autenticação Cognito e infraestrutura CDK ou Terraform. Peça a um assistente de IA para estruturá-la para você, ou execute os geradores você mesmo — ambas as rotas chegam ao mesmo workspace.

Com IA

1. Abra o workspace em seu assistente de codificação de IA.

   Novos workspaces vêm com o servidor MCP do plugin já configurado para Kiro, Claude Code, Cursor, Gemini CLI, GitHub Copilot e OpenAI Codex, então seu assistente pode consultar os geradores do plugin e executá-los sem nenhuma configuração.

2. Peça pela aplicação:

   Prompt

   Create a tRPC API called demo-api, and a React website called demo-website. Add Cognito authentication to the website, connect the website to the API, and add an infrastructure project called infra. Then instantiate the generated infrastructure components so the website and API deploy, granting authenticated users access to the API.

   Seu assistente descobre os geradores através do servidor MCP e os executa, na ordem que suas dependências precisam. Revise as alterações que ele faz e então continue no Passo 3.

Com a CLI

Execute os geradores que estruturam a aplicação. Use o botão abaixo para copiá-los todos, ou execute cada um você mesmo conforme descrito abaixo do diagrama.

CDK

Loading the diagram…

Terraform

Loading the diagram…

Dependendo do tipo de projeto que você está construindo, você pode escolher qualquer combinação de geradores para inicializar rapidamente seu projeto. Confira os Geradores na barra de navegação à esquerda para ver a lista completa de opções, ou experimente o construtor de grafos para construir seu workspace visualmente.

Adicionar uma API tRPC

Execute este gerador@aws/nx-plugin:ts#api

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#api --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#api --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#api --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#api --no-interactive

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

Opções desta etapa2

nameObrigatório

framework

trpc

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

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

Adicionar um Website React

Execute este gerador@aws/nx-plugin:ts#website

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

Opções desta etapa1

nameObrigatório

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

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

Adicionar Autenticação Cognito

Execute este gerador@aws/nx-plugin:ts#website#auth

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website#auth --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website#auth --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website#auth --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website#auth --no-interactive

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

Opções desta etapa1

projectObrigatório

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

Isso configura a infraestrutura necessária e o código React para adicionar Autenticação Cognito ao seu website.

Conectar Frontend ao Backend

Execute este gerador@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:connection --no-interactive

npm

$ npx nx g @aws/nx-plugin:connection --no-interactive

bun

$ bunx nx g @aws/nx-plugin:connection --no-interactive

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 - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Opções desta etapa2

sourceProjectObrigatório

targetProjectObrigatório

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

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

Adicionar Infraestrutura

Adicione o projeto de infraestrutura com base no seu provedor IAC escolhido.

CDK

Execute este gerador@aws/nx-plugin:ts#infra

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#infra --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#infra --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#infra --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#infra --no-interactive

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

Opções desta etapa1

nameObrigatório

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

Isso configura uma CDK App que você pode usar para implantar sua infraestrutura na AWS.

Terraform

Execute este gerador@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:terraform#project --no-interactive

npm

$ npx nx g @aws/nx-plugin:terraform#project --no-interactive

bun

$ bunx nx g @aws/nx-plugin:terraform#project --no-interactive

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 - terraform#project
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Opções desta etapa1

nameObrigatório

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

Isso configura um projeto Terraform que você pode usar para implantar sua infraestrutura na AWS.

Passo 3: Executar seu Website e API Localmente

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

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

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

As alterações em seu website e API serão refletidas em tempo real, pois tanto o website local quanto os servidores de API farão hot-reload.

Experimente: chame a API do seu website

Passo 4: Definir Recursos na Nuvem e Implantar na AWS

CDK

Abra packages/infra/src/stacks/application-stack.ts e adicione o seguinte código:

import {
  DemoApi,
  DemoWebsite,
  UserIdentity,
} from '@my-project/common-constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: 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');
  }
}

Isso é todo o CDK que precisamos escrever para implantar nossa aplicação full stack.

Terraform

Abra packages/infra/src/main.tf e adicione o seguinte código:

# Deploy user identity
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Deploy API
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Grant authenticated users access to invoke the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Policy to allow authenticated users to invoke the API"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = "execute-api:Invoke"
        Resource = "${module.demo_api.api_execution_arn}/*/*"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

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

module "demo_website" {
  source = "../../common/terraform/src/app/static-websites/demo-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  depends_on = [module.user_identity, module.demo_api]
}

# Print the website URL and user pool id when the deployment finishes
output "website_url" {
  value = module.demo_website.website_url
}

output "user_pool_id" {
  value = module.user_identity.user_pool_id
}

Isso é todo o Terraform que precisamos escrever para implantar nossa aplicação full stack.

Construir e Implantar a Infraestrutura

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

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Corrigindo Erros de Lint e Formatação

Se você encontrar algum erro de lint ou formatação, você pode executar o seguinte comando para corrigi-los automaticamente.

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

O workspace está fora de sincronia

Se a compilação reportar The workspace is out of sync, aceite o prompt para sincronizar o workspace ou execute o seguinte comando de sincronização diretamente antes de tentar novamente a compilação:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Isso escreve as referências de projeto TypeScript e as entradas de dependência do package.json que suas importações requerem.

Faça o bootstrap da sua infraestrutura:

CDK

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Regiões de Bootstrap

O bootstrap do CDK é necessário tanto para sua região AWS de implantação de destino quanto para us-east-1 para permitir a implantação do AWS WAF WebACL para o website. Se você estiver implantando em outro lugar, faça o bootstrap de us-east-1 também:

pnpm

pnpm nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

yarn

yarn nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

npm

npx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

bun

bunx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

Terraform

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Configuração Única

O bootstrap do Terraform cria um bucket S3 para armazenar seus arquivos de estado do Terraform. Isso só precisa ser feito uma vez por combinação de conta/região AWS.

Implante seu projeto:

CDK

pnpm

pnpm nx deploy-sandbox infra

yarn

yarn nx deploy-sandbox infra

npm

npx nx deploy-sandbox infra

bun

bunx nx deploy-sandbox infra

Terraform

pnpm

pnpm nx apply infra

yarn

yarn nx apply infra

npm

npx nx apply infra

bun

bunx nx apply infra

Planejar Antes de Aplicar

Este comando primeiro executará terraform plan para mostrar quais alterações serão feitas e, em seguida, aplicará essas alterações para implantar sua infraestrutura.

Passo 5: Testar o Website com Recursos na Nuvem Implantados

1. Busque o arquivo runtime-config.json:

   pnpm

   pnpm nx load-runtime-config demo-website

   yarn

   yarn nx load-runtime-config demo-website

   npm

   npx nx load-runtime-config demo-website

   bun

   bunx nx load-runtime-config demo-website

2. Inicie o servidor de website local

   pnpm

   pnpm nx serve demo-website

   yarn

   yarn nx serve demo-website

   npm

   npx nx serve demo-website

   bun

   bunx nx serve demo-website

Seu website estará disponível em http://localhost:4200 e apontará para os recursos que você implantou para a API e autenticação.

Para fazer login, você precisará criar um usuário no user pool do Cognito.

Clique aqui para instruções usando a AWS CLI

Seu website também é servido pelo CloudFront. Abra o nome de domínio de distribuição (que é impresso no seu terminal após a implantação) para usar a versão executando inteiramente na AWS.

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

Passo 6: Limpar

Quando terminar, exclua os recursos que você implantou para evitar custos contínuos:

CDK

pnpm

pnpm nx destroy-sandbox infra

yarn

yarn nx destroy-sandbox infra

npm

npx nx destroy-sandbox infra

bun

bunx nx destroy-sandbox infra

Recursos Retidos

O user pool do Cognito é criado com proteção contra exclusão habilitada, portanto ele não é removido automaticamente. Exclua-o (e a função IAM que o Cognito usa para enviar mensagens SMS) manualmente se você não precisar mais deles.

Terraform

pnpm

pnpm nx destroy infra

yarn

yarn nx destroy infra

npm

npx nx destroy infra

bun

bunx nx destroy infra

Recursos Retidos

O user pool do Cognito é criado com proteção contra exclusão habilitada, portanto ele não é removido automaticamente (o comando destroy reportará uma falha). Exclua-o (e a função IAM que o Cognito usa para enviar mensagens SMS) manualmente se você não precisar mais deles.

Para remover os recursos de bootstrap, siga abaixo:

CDK

Exclua a stack de bootstrap em todas as regiões que você fez bootstrap, incluindo us-east-1. Isso remove as funções de bootstrap e o repositório de imagens de contêiner:

aws cloudformation delete-stack --stack-name CDKToolkit --region <region>

Asset Bucket

O bucket de assets é retido propositalmente, então exclua-o separadamente.

Terraform

pnpm

pnpm nx bootstrap-destroy infra

yarn

yarn nx bootstrap-destroy infra

npm

npx nx bootstrap-destroy infra

bun

bunx nx bootstrap-destroy infra

Seu Estado do Terraform Também É Excluído

Isso esvazia e exclui o bucket S3 que contém seu estado do Terraform, então execute-o apenas quando você tiver removido toda a infraestrutura implantada.

---

Próximos Passos

• Dungeon Adventure Tutorial — construa um jogo de aventura de masmorra com IA full-stack, para um passo a passo mais aprofundado do que este guia.
• Workspaces — como seu workspace está organizado e a configuração que os geradores compartilham.
• Add to an Existing Project — adote o plugin em sua base de código existente.