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 rápidamente en AWS.

Consejo

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

Requisitos Previos

Se necesitan las siguientes dependencias globales antes de continuar:

• Git
• Node >= 22 (Recomendamos usar herramientas como NVM para gestionar versiones de Node)
  • Verificar ejecutando node --version
• PNPM >= 10 (También puedes usar Yarn >= 4, Bun >= 1 o NPM >= 10 si lo prefieres)
  • Verificar ejecutando pnpm --version, yarn --version, bun --version o npm --version
• UV >= 0.5.29
  1. Instalar Python 3.12 ejecutando: uv python install 3.12.0
  2. Verificar con uv python list --only-installed
• AWS Credentials configuradas para tu cuenta de AWS objetivo (donde se desplegará tu aplicación)
• Si usas VSCode, recomendamos instalar el Nx Console VSCode Plugin.

Consejo

Si utilizas un asistente de IA como Amazon Q Developer, Cursor, Claude Code o Cline, también puedes considerar instalar el Plugin 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 añadiremos 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.

Añadir 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.

Añadir 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.

Añadir 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#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 añadir 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
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 garantizar que tu sitio web pueda llamar a tu API tRPC.

Añadir 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: Ejecutar tu sitio web y API localmente

Usa el siguiente comando para iniciar servidores de desarrollo local 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

Abre packages/infra/src/stacks/application-stack.ts y añade 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 CDK que necesitamos escribir 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

Ejecuta el siguiente comando para desplegar tu proyecto:

pnpm

pnpm nx run infra:deploy --all

yarn

yarn nx run infra:deploy --all

npm

npx nx run infra:deploy --all

bun

bunx nx run infra:deploy --all

Consejo

Necesitarás asegurarte de que tu entorno AWS ha sido configurado apropiadamente para CDK.

Se requiere configuración inicial (bootstrapping) de CDK tanto para tu región de despliegue objetivo en AWS como para us-east-1 para permitir el despliegue del WebACL de AWS WAF para el sitio web.

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Paso 5: Probar el sitio web con 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 la autenticación.

---

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