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.

Tutorial Full-Stack

Para un tutorial más detallado sobre la construcción de una aplicación full-stack, consulta el Tutorial de Aventura en Mazmorras.

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

Recomendados

• PNPM >= 11 (también puedes usar Yarn >= 4, Bun >= 1, o NPM >= 10 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.

Configuración del Asistente de IA

Si utilizas un Asistente de IA como Kiro, Kiro CLI, Cursor, Claude Code o Cline, es posible que también desees instalar el servidor MCP de Nx Plugin for AWS.

Paso 1: Inicializar un Nuevo Espacio de Trabajo Nx

Ejecuta el siguiente comando para crear un espacio de trabajo Nx con el gestor de paquetes de tu elección:

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

Elegir un Proveedor de IaC

Se te pedirá tu proveedor preferido de infraestructura como código (IaC), ya sea CDK o Terraform. Puedes omitir la solicitud ejecutando el comando con --iac, por ejemplo:

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

Una vez completado, navega al directorio del proyecto:

cd my-project

Paso 2: Usar Generadores para Estructurar tu Proyecto

Agregaremos una API tRPC, un Sitio Web React, Autenticación Cognito e Infraestructura CDK o Terraform en esta guía de inicio rápido. 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.

Como atajo, puedes usar el botón a continuación para copiar los comandos para estructurar la aplicación completa.

Loading the diagram…

Construir con IA

El Nx Plugin for AWS MCP Server ya está configurado en tu espacio de trabajo, por lo que puedes pedirle a tu agente de codificación de IA favorito como Kiro o Claude que construya estos proyectos por ti en lugar de escribir los comandos CLI tú mismo.

De lo contrario, sigue los pasos a continuación para ejecutar cada generador tú mismo.

Agregar una 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

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

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

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

Agregar un Sitio Web 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

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

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 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
   • name: demo-website
6. Haga clic en Generate

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

Agregar Autenticación 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

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

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

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

Conectar Frontend con 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

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

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

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

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

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

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 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
   • name: infra
6. Haga clic en Generate

Esto configura una Aplicación CDK que puedes usar para desplegar tu infraestructura en 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

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

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 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
   • name: infra
6. Haga clic en Generate

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.

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 { 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');
  }
}

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:

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

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

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

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

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.

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.

---

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