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:

Requisitos

• 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 da AWS 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 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 preferência:

pnpm

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

yarn

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

npm

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

bun

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

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@21.4.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

yarn

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

npm

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

bun

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

Terraform

pnpm

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

yarn

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

npm

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

bun

npx create-nx-workspace@21.4.1 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=Terraform --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

Neste guia rápido, adicionaremos uma API tRPC, Website React, Autenticação Cognito e Infraestrutura CDK/Terraform. Dependendo do tipo de projeto, 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 - 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 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 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

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ê implantou com sucesso uma aplicação full-stack usando @aws/nx-plugin!