Guía de Inicio Rápido

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

Consejo

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

Requisitos previos

Se necesitan las siguientes dependencias globales antes de continuar:

• 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)
• Si usas VSCode, recomendamos instalar el Complemento Nx Console para VSCode.

Consejo

Si utilizas un Asistente de IA como Amazon Q Developer, Cursor, Claude Code o Cline, también puedes querer instalar el complemento de 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.0.3 my-project --pm=pnpm --preset=@aws/nx-plugin --ci=skip

yarn

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

npm

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

bun

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

Una vez completado, navega 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 con Cognito e infraestructura CDK. Dependiendo del tipo de proyecto que estés construyendo, puedes elegir cualquier combinación de generadores para inicializar rápidamente tu proyecto. Consulta 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 dentro de 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#cloudscape-website
5. Complete los parámetros requeridos
   • name: demo-website
6. Haga clic en Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website

yarn

yarn nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website

npm

npx nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website

bun

bunx nx g @aws/nx-plugin:ts#cloudscape-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#cloudscape-website --name=demo-website --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run

npm

npx nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run

bun

bunx nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run

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

Agregar autenticación con 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#cloudscape-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#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

yarn

yarn nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

npm

npx nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

bun

bunx nx g @aws/nx-plugin:ts#cloudscape-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#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

npm

npx nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

bun

bunx nx g @aws/nx-plugin:ts#cloudscape-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 con 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-backend
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-backend

yarn

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

npm

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

bun

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

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

yarn

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

npm

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

bun

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

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

Agregar infraestructura 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.

Paso 3: Definir recursos en la nube y desplegar en AWS

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

Esto es todo el código CDK 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 lint, puedes ejecutar este 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

Paso 4: Ejecutar el frontend localmente

1. Obtén el archivo runtime-config.json:

   pnpm

   pnpm nx run @demo/demo-website:load:runtime-config

   yarn

   yarn nx run @demo/demo-website:load:runtime-config

   npm

   npx nx run @demo/demo-website:load:runtime-config

   bun

   bunx nx run @demo/demo-website:load:runtime-config

2. Inicia el servidor local del sitio web

   pnpm

   pnpm nx run @demo/demo-website:serve

   yarn

   yarn nx run @demo/demo-website:serve

   npm

   npx nx run @demo/demo-website:serve

   bun

   bunx nx run @demo/demo-website:serve

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

---

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