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.

Tutorial Full-Stack

Para um tutorial mais aprofundado sobre como construir uma aplicação full-stack, confira o Tutorial Dungeon Adventure.

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.0
  2. verifique com uv python list --only-installed

Recomendado

• PNPM >= 11 (você também pode usar Yarn >= 4, Bun >= 1, ou NPM >= 10 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.

Configuração do Assistente de IA

Se você usa um Assistente de IA como Kiro, Kiro CLI, Cursor, Claude Code ou Cline, você também pode desejar instalar o servidor MCP do Nx Plugin for AWS.

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

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

Escolhendo um Provedor IaC

Você será solicitado a escolher seu provedor de infraestrutura como código (IaC) preferido, seja CDK ou Terraform. Você pode pular o prompt executando o comando com --iac, por exemplo:

CDK

pnpm

pnpm create @aws/nx-workspace my-project --iac=cdk

yarn

yarn create @aws/nx-workspace my-project --iac=cdk

npm

npm create @aws/nx-workspace -- my-project --iac=cdk

bun

bun create @aws/nx-workspace my-project --iac=cdk

Terraform

pnpm

pnpm create @aws/nx-workspace my-project --iac=terraform

yarn

yarn create @aws/nx-workspace my-project --iac=terraform

npm

npm create @aws/nx-workspace -- my-project --iac=terraform

bun

bun create @aws/nx-workspace my-project --iac=terraform

Quando concluído, navegue até o diretório do projeto:

cd my-project

Passo 2: Usar Geradores para Estruturar seu Projeto

Vamos adicionar uma API tRPC, um Website React, Autenticação Cognito e Infraestrutura CDK ou Terraform neste guia de início 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 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.

Como atalho, você pode usar o botão abaixo para copiar os comandos para estruturar a aplicação completa.

Loading the diagram…

Construa com IA

O Nx Plugin for AWS MCP Server já está configurado em seu workspace, então você pode pedir ao seu agente de codificação de IA favorito, como Kiro ou Claude, para construir esses projetos para você em vez de digitar os comandos CLI você mesmo.

Caso contrário, siga os passos abaixo para executar cada gerador você mesmo.

Adicionar uma API tRPC

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

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
   • name: demo-api
   • framework: trpc
   • auth: iam
6. Clique em Generate

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

Adicionar um Website React

CLI

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

yarn

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

npm

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

bun

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

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

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

Adicionar Autenticação Cognito

CLI

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

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
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Clique em Generate

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

Conectar Frontend ao Backend

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Clique em Generate

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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 --no-interactive --dry-run

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

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

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

Terraform

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

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

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.

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 { Stack, StackProps } from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from '@my-project/common-constructs';
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:

# Include metrics tracking for @aws/nx-plugin usage
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# 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]
}

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

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

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

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.

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.

---

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