Guia de Início Rápido

Este guia orienta você através dos fundamentos de 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 Dungeon Adventure.

Pré-requisitos

As seguintes dependências globais são necessárias antes de prosseguir:

Requeridos

• Git
• Node >= 22 (Recomendamos usar algo como NVM para gerenciar suas versões do Node)
  • verifique executando node --version
• PNPM >= 10 (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
• UV >= 0.5.29
  1. instale o Python 3.12 executando: uv python install 3.12.0
  2. verifique com uv python list --only-installed
• AWS Credentials configuradas para sua conta AWS de destino (onde sua aplicação será implantada)

Recomendados

• Docker é necessário para alguns geradores.
• Terraform >= 1.12 é necessário se você optar por usar isso para infraestrutura como código em vez do CDK
  • verifique executando terraform --version
• Se você usa VSCode, recomendamos instalar o Nx Console VSCode Plugin.

Dica

Se você usa um Assistente de IA como Kiro, Amazon Q Developer, Cursor, Claude Code ou Cline, você também pode querer 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 preferência:

pnpm

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

yarn

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

npm

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

bun

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

Dica

Você será questionado sobre seu provedor de infraestrutura como código (IaC) preferido, CDK ou Terraform. Você pode pular a pergunta executando o comando com --iacProvider, ex:

CDK

pnpm

npx create-nx-workspace@22.5.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

yarn

npx create-nx-workspace@22.5.1 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

npm

npx create-nx-workspace@22.5.1 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

bun

npx create-nx-workspace@22.5.1 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

Terraform

pnpm

npx create-nx-workspace@22.5.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --aiAgents

yarn

npx create-nx-workspace@22.5.1 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --aiAgents

npm

npx create-nx-workspace@22.5.1 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --aiAgents

bun

npx create-nx-workspace@22.5.1 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --aiAgents

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

cd my-project

Passo 2: Usar Geradores para Estruturar seu Projeto

Neste guia rápido, adicionaremos uma API tRPC, Website React, Autenticação Cognito e Infraestrutura CDK ou Terraform. 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 na pasta packages/demo-api.

Adicionar um Website 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 estruturará um novo website 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 configurará a infraestrutura necessária e o código React para adicionar Autenticação Cognito ao seu website.

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 - 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:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin: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:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

yarn

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

npm

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

bun

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

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

Adicionar Infraestrutura

Adicione o projeto de infraestrutura baseado no seu provedor IaC escolhido.

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.

Terraform

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

yarn

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

npm

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

bun

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

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 locais de desenvolvimento para seu website 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 website estará disponível em http://localhost:4200.

Alterações no website e 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

CDK

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.

Terraform

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

# Inclui rastreamento de métricas para uso do @aws/nx-plugin
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# Implanta identidade do usuário
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

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

# Concede acesso a usuários autenticados para invocar a API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Política para permitir que usuários autenticados invoquem a 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
}

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

Este é todo o código Terraform 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 build

yarn

yarn build

npm

npm run build

bun

bun build

Dica

Se encontrar erros 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

Inicialize sua infraestrutura:

CDK

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Dica

O bootstrap do CDK é necessário tanto para a região AWS de implantação quanto para us-east-1 para permitir a implantação do AWS WAF WebACL para o website.

Terraform

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Dica

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 run infra:deploy "my-project-sandbox/*"

yarn

yarn nx run infra:deploy "my-project-sandbox/*"

npm

npx nx run infra:deploy "my-project-sandbox/*"

bun

bunx nx run infra:deploy "my-project-sandbox/*"

Terraform

pnpm

pnpm nx run infra:apply

yarn

yarn nx run infra:apply

npm

npx nx run infra:apply

bun

bunx nx run infra:apply

Dica

Este comando primeiro executará terraform plan para mostrar as alterações planejadas, depois aplicará essas alterações para implantar sua infraestrutura.

Passo 5: Testar o Website 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 website

   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 website estará disponível em http://localhost:4200 e apontará para os recursos implantados da API e autenticação.

---

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