Guía de Inicio Rápido

Esta guía te lleva a través de los conceptos básicos de instalación y uso de @aws/nx-plugin para construir proyectos rápidamente en AWS.

Requisitos Previos

Las siguientes dependencias globales son necesarias antes de continuar:

Requeridos

• Git
• Node >= 22 (Recomendamos usar algo como NVM para gestionar tus versiones de node)
  • verifica ejecutando node --version
• UV >= 0.5.29
  1. instala Python 3.14 ejecutando: uv python install 3.14
  2. verifica con uv python list --only-installed

Recomendados

• PNPM >= 11 (también puedes usar Yarn >= 4, Bun >= 1, o NPM >= 11 si lo prefieres)
  • verifica ejecutando pnpm --version, yarn --version, bun --version o npm --version
• AWS Credentials configuradas para tu cuenta de AWS de destino son necesarias para desplegar tu aplicación (así como para algunos flujos de trabajo de desarrollo local).
• Docker o Finch >= 1.6.0 es necesario para algunos generadores. Para Docker, las compilaciones multiplataforma deben estar configuradas; Finch soporta compilaciones multiplataforma de forma predeterminada.
• Terraform >= 1.12 es necesario si eliges usar esto para infraestructura como código en lugar de CDK
  • verifica ejecutando terraform --version
• Si estás usando VSCode, recomendamos instalar el Nx Console VSCode Plugin.

Paso 1: Crear un Espacio de Trabajo

Crea un espacio de trabajo Nx con el gestor de paquetes de tu elección, y abre el directorio que crea:

Cree su espacio de trabajo@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

Construya su comando3

workspaceRequerido

iac

cdkterraform

containers

inferdockerfinch

cd my-project

Se te solicita elegir tu proveedor de infraestructura como código, ya sea CDK o Terraform.

Paso 2: Construir tu Aplicación

Construiremos una aplicación full-stack: una API tRPC, un sitio web React, autenticación Cognito e infraestructura CDK o Terraform. Pídele a un asistente de IA que la estructure por ti, o ejecuta los generadores tú mismo — ambas rutas llegan al mismo espacio de trabajo.

Con IA

1. Abre el espacio de trabajo en tu asistente de codificación de IA.

   Los nuevos espacios de trabajo vienen con el servidor MCP del plugin ya configurado para Kiro, Claude Code, Cursor, Gemini CLI, GitHub Copilot y OpenAI Codex, por lo que tu asistente puede buscar los generadores del plugin y ejecutarlos sin ninguna configuración.

2. Solicita la aplicación:

   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.

   Tu asistente descubre los generadores a través del servidor MCP y los ejecuta, en el orden que sus dependencias necesitan. Revisa los cambios que realiza, luego continúa en el Paso 3.

Con el CLI

Ejecuta los generadores que estructuran la aplicación. Usa el botón a continuación para copiarlos todos, o ejecuta cada uno tú mismo como se describe debajo del diagrama.

CDK

Loading the diagram…

Terraform

Loading the diagram…

Dependiendo del tipo de proyecto que estés construyendo, puedes elegir cualquier combinación de generadores para inicializar rápidamente tu proyecto. Consulta los Generadores en la barra de navegación a la izquierda para ver la lista completa de opciones, o prueba el constructor de grafos para construir tu espacio de trabajo visualmente.

Agregar una API tRPC

Ejecute este generador@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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#api
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones de este paso2

nameRequerido

framework

trpc

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Esto creará la API dentro de la carpeta packages/demo-api.

Agregar un Sitio Web React

Ejecute este generador@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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#website
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones de este paso1

nameRequerido

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Esto estructura un nuevo sitio web React en packages/demo-website.

Agregar Autenticación Cognito

Ejecute este generador@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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#website#auth
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones de este paso1

projectRequerido

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Esto configura la infraestructura necesaria y el código React para agregar Autenticación Cognito a tu sitio web.

Conectar Frontend con Backend

Ejecute este generador@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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones de este paso2

sourceProjectRequerido

targetProjectRequerido

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Esto configura los proveedores necesarios para asegurar que tu sitio web pueda llamar a tu API tRPC.

Agregar Infraestructura

Agrega el proyecto de infraestructura basado en tu proveedor IAC elegido.

CDK

Ejecute este generador@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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#infra
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones de este paso1

nameRequerido

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Esto configura una Aplicación CDK que puedes usar para desplegar tu infraestructura en AWS.

Terraform

Ejecute este generador@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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - terraform#project
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones de este paso1

nameRequerido

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Esto configura un proyecto Terraform que puedes usar para desplegar tu infraestructura en AWS.

Paso 3: Ejecutar tu Sitio Web y API Localmente

Usa el siguiente comando para iniciar servidores de desarrollo locales para tu sitio web y sus APIs conectadas:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Tu sitio web estará disponible en http://localhost:4200.

Los cambios tanto en tu sitio web como en la API se reflejarán en tiempo real ya que tanto el sitio web local como los servidores de API se recargarán automáticamente.

Pruébalo: llama a la API desde tu sitio web

Paso 4: Definir Recursos en la Nube y Desplegar en AWS

CDK

Abre packages/infra/src/stacks/application-stack.ts y agrega el siguiente 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');
  }
}

Esto es todo el CDK que necesitamos escribir para desplegar nuestra aplicación full stack.

Terraform

Abre packages/infra/src/main.tf y agrega el siguiente 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
}

Esto es todo el Terraform que necesitamos escribir para desplegar nuestra aplicación full stack.

Construir y Desplegar la Infraestructura

A continuación, ejecuta el siguiente comando para construir tu proyecto:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Corregir Errores de Lint y Formato

Si encuentras algún error de lint o formato, puedes ejecutar el siguiente comando para corregirlos automáticamente.

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

El espacio de trabajo está desincronizado

Si la compilación reporta The workspace is out of sync, acepta la solicitud para sincronizar el espacio de trabajo o ejecuta el siguiente comando de sincronización directamente antes de reintentar la compilación:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Esto escribe las referencias de proyecto TypeScript y las entradas de dependencia de package.json que tus importaciones requieren.

Inicializa tu infraestructura:

CDK

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Regiones de Bootstrap

El bootstrap de CDK es requerido tanto para tu región AWS de despliegue objetivo, como para us-east-1 para permitir el despliegue del AWS WAF WebACL para el sitio web. Si estás desplegando en otro lugar, inicializa us-east-1 también:

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

Configuración Única

El bootstrap de Terraform crea un bucket S3 para almacenar tus archivos de estado de Terraform. Esto solo necesita hacerse una vez por combinación de cuenta/región de AWS.

Despliega tu proyecto:

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

Planificar Antes de Aplicar

Este comando primero ejecutará terraform plan para mostrarte qué cambios se realizarán, luego aplicará esos cambios para desplegar tu infraestructura.

Paso 5: Probar el Sitio Web con Recursos en la Nube Desplegados

1. Obtén el archivo 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. Inicia el servidor del sitio web 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

Tu sitio web estará disponible en http://localhost:4200, y apuntará a los recursos que desplegaste para la API y la autenticación.

Para iniciar sesión, necesitarás crear un usuario en el grupo de usuarios de Cognito.

Haz clic aquí para ver las instrucciones usando el AWS CLI

Tu sitio web también se sirve desde CloudFront. Abre el nombre de dominio de su distribución (que se imprime en tu terminal después del despliegue) para usar la versión que se ejecuta completamente en AWS.

¡Felicitaciones! 🎉 ¡Has construido y desplegado exitosamente una aplicación full-stack usando @aws/nx-plugin!

Paso 6: Limpiar

Cuando hayas terminado, elimina los recursos que desplegaste para evitar costos continuos:

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 Retenidos

El grupo de usuarios de Cognito se crea con protección contra eliminación habilitada, por lo que no se elimina automáticamente. Elimínalo (y el rol IAM que Cognito usa para enviar mensajes SMS) manualmente si ya no los necesitas.

Terraform

pnpm

pnpm nx destroy infra

yarn

yarn nx destroy infra

npm

npx nx destroy infra

bun

bunx nx destroy infra

Recursos Retenidos

El grupo de usuarios de Cognito se crea con protección contra eliminación habilitada, por lo que no se elimina automáticamente (el comando destroy reportará un fallo). Elimínalo (y el rol IAM que Cognito usa para enviar mensajes SMS) manualmente si ya no los necesitas.

Para eliminar los recursos de bootstrap, sigue las instrucciones a continuación:

CDK

Elimina el stack de bootstrap en cada región que inicializaste, incluyendo us-east-1. Esto elimina los roles de bootstrap y el repositorio de imágenes de contenedor:

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

Asset Bucket

El bucket de activos se retiene a propósito, así que elimínalo por separado.

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

Tu Estado de Terraform También Se Elimina

Esto vacía y elimina el bucket S3 que contiene tu estado de Terraform, así que ejecútalo solo una vez que hayas eliminado toda la infraestructura desplegada.

---

Próximos Pasos

• Dungeon Adventure Tutorial — construye un juego de aventura en mazmorras con IA full-stack, para un recorrido más detallado que esta guía.
• Workspaces — cómo está organizado tu espacio de trabajo, y la configuración que comparten los generadores.
• Add to an Existing Project — adopta el plugin en tu base de código existente.