Guía de Inicio Rápido

Esta guía te guiará a través de los conceptos básicos de instalar y usar @aws/nx-plugin para construir proyectos en AWS rápidamente.

Consejo

Para un tutorial más detallado sobre cómo construir una aplicación full-stack, revisa la Tutorial de Dungeon Adventure.

Requisitos previos

Se necesitan las siguientes dependencias globales antes de continuar:

Requeridos

• Git (instalación de Git)
• Node >= 22 (Recomendamos usar algo como NVM para gestionar tus versiones de Node)
  • Verifica ejecutando node --version
• PNPM >= 10 (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
• UV >= 0.5.29
  1. Instala Python 3.12 ejecutando: uv python install 3.12.0
  2. Verifica con uv python list --only-installed
• Credenciales de AWS configuradas para tu cuenta de AWS de destino (donde se desplegará tu aplicación)

Recomendados

• Docker es necesario para algunos generadores.
• Terraform >= 1.12 es necesario si eliges usar esta herramienta para infraestructura como código en lugar de CDK
  • verifica ejecutando terraform --version
• Si usas VSCode, recomendamos instalar el Nx Console VSCode Plugin.

Consejo

Si utilizas un Asistente de IA como Kiro, Amazon Q Developer, Cursor, Claude Code o Cline, también puedes instalar el complemento NX para AWS MCP server.

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

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

yarn

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

npm

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

bun

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

Consejo

Se te pedirá que elijas tu proveedor de infraestructura como código (IaC), ya sea CDK o Terraform. Puedes omitir esta pregunta ejecutando el comando con --iacProvider, por ejemplo:

CDK

pnpm

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

yarn

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

npm

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

bun

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

Terraform

pnpm

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

yarn

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

npm

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

bun

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

Una vez completado, accede al directorio del proyecto:

cd my-project

Paso 2: Usar generadores para estructurar tu proyecto

En esta guía rápida, agregaremos una API tRPC, un sitio web React, autenticación Cognito e infraestructura CDK o Terraform. Dependiendo del tipo de proyecto que estés construyendo, puedes elegir cualquier combinación de generadores para inicializar rápidamente tu proyecto. Revisa las Guías en la barra de navegación izquierda para ver la lista completa de opciones.

Agregar una API tRPC

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#trpc-api
5. Complete los parámetros requeridos
   • name: demo-api
   • auth: IAM
6. Haga clic en 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

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

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

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

Agregar un sitio web React

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#react-website
5. Complete los parámetros requeridos
   • name: demo-website
6. Haga clic en 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

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

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

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

Agregar autenticación Cognito

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#react-website#auth
5. Complete los parámetros requeridos
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Haga clic en 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

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

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

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

Conectar el frontend al backend

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 - api-connection
5. Complete los parámetros requeridos
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Haga clic en 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

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

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

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

Agregar infraestructura

Agrega el proyecto de infraestructura según tu proveedor IaC elegido.

CDK

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

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

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

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

Terraform

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

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

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

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 locales de desarrollo para tu sitio web y sus 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

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 ambos servidores locales 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 * 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 es todo el código CDK necesario 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"
}

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

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

Este es todo el código Terraform necesario para desplegar nuestra aplicación full-stack.

Construir y desplegar la infraestructura

Luego, ejecuta el siguiente comando para construir tu proyecto:

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

Consejo

Si encuentras errores de linting, puedes ejecutar el siguiente comando para corregirlos automáticamente.

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

Inicializa tu infraestructura:

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

Consejo

Se requiere inicialización de CDK tanto para la región AWS de despliegue objetivo como para us-east-1 para permitir el despliegue del WebACL de AWS WAF para el sitio web.

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

Consejo

La inicialización 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 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

Consejo

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

Paso 5: Probar el sitio web con los recursos en la nube desplegados

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

   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

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

---

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