Guía de Inicio Rápido

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

Consejo

Para un tutorial más detallado sobre cómo construir una aplicación full-stack, revisa 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 agregaremos una API tRPC, un Sitio Web React, Autenticación Cognito e Infraestructura CDK. Dependiendo del tipo de proyecto que estés construyendo, puedes elegir cualquier combinación de generadores para configurar 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 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
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 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 implementar tu infraestructura en AWS.

Paso 3: Definir Recursos en la Nube e Implementar 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');
  }
}

Este es todo el código CDK que necesitamos escribir para implementar nuestra aplicación full-stack.

Construir e Implementar 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 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

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 e implementado exitosamente una aplicación full-stack usando @aws/nx-plugin!