Guía de Inicio Rápido
Esta guía te lleva por los conceptos básicos de instalar y usar @aws/nx-plugin
para construir proyectos rápidamente en AWS.
Requisitos Previos
Se necesitan las siguientes dependencias globales antes de continuar:
- Git
- Node >= 22 (Recomendamos usar herramientas como NVM para gestionar tus versiones de Node)
- Verifica ejecutando
node --version
- Verifica ejecutando
- PNPM >= 10 (también puedes usar Yarn >= 4, Bun >= 1 o NPM >= 10 si lo prefieres)
- Verifica ejecutando
pnpm --version
,yarn --version
,bun --version
onpm --version
- Verifica ejecutando
- UV >= 0.5.29
- Instala Python 3.12 ejecutando:
uv python install 3.12.0
- Verifica con
uv python list --only-installed
- Instala Python 3.12 ejecutando:
- 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.
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:
npx create-nx-workspace@~20.6.3 my-project --pm=pnpm --preset=ts --ci=skip --formatter=prettier
npx create-nx-workspace@~20.6.3 my-project --pm=yarn --preset=ts --ci=skip --formatter=prettier
npx create-nx-workspace@~20.6.3 my-project --pm=npm --preset=ts --ci=skip --formatter=prettier
npx create-nx-workspace@~20.6.3 my-project --pm=bun --preset=ts --ci=skip --formatter=prettier
Una vez completado, navega al directorio del proyecto:
cd my-project
Paso 2: Agregar el Plugin Nx para AWS
Instala el plugin con:
pnpm add -Dw @aws/nx-plugin
yarn add -D @aws/nx-plugin
npm install --legacy-peer-deps -D @aws/nx-plugin
bun install -D @aws/nx-plugin
Paso 3: Usar Generadores para Estructurar tu Proyecto
Agregaremos una API tRPC, un Sitio Web React, Autenticación con Cognito e Infraestructura CDK en esta guía rápida. 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 a la izquierda para ver la lista completa de opciones.
Agregar una API tRPC
- Instale el Nx Console VSCode Plugin si aún no lo ha hecho
- Abra la consola Nx en VSCode
- Haga clic en
Generate (UI)
en la sección "Common Nx Commands" - Busque
@aws/nx-plugin - ts#trpc-api
- Complete los parámetros requeridos
- apiName: demo-api
- Haga clic en
Generate
pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api
yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api
npx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api
bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api
También puede realizar una ejecución en seco para ver qué archivos se cambiarían
pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --dry-run
yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --dry-run
npx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --dry-run
bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=demo-api --dry-run
Esto creará la API dentro de la carpeta packages/demo-api
.
Agregar un Sitio Web React
- Instale el Nx Console VSCode Plugin si aún no lo ha hecho
- Abra la consola Nx en VSCode
- Haga clic en
Generate (UI)
en la sección "Common Nx Commands" - Busque
@aws/nx-plugin - ts#cloudscape-website
- Complete los parámetros requeridos
- name: demo-website
- Haga clic en
Generate
pnpm nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website
yarn nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website
npx nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website
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 nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run
yarn nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run
npx nx g @aws/nx-plugin:ts#cloudscape-website --name=demo-website --dry-run
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
- Instale el Nx Console VSCode Plugin si aún no lo ha hecho
- Abra la consola Nx en VSCode
- Haga clic en
Generate (UI)
en la sección "Common Nx Commands" - Busque
@aws/nx-plugin - ts#cloudscape-website#auth
- Complete los parámetros requeridos
- project: @my-project/demo-website
- cognitoDomain: my-demo
- Haga clic en
Generate
pnpm nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
yarn nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
npx nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
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 nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
yarn nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
npx nx g @aws/nx-plugin:ts#cloudscape-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
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 Frontend con Backend
- Instale el Nx Console VSCode Plugin si aún no lo ha hecho
- Abra la consola Nx en VSCode
- Haga clic en
Generate (UI)
en la sección "Common Nx Commands" - Busque
@aws/nx-plugin - api-connection
- Complete los parámetros requeridos
- sourceProject: @my-project/demo-website
- targetProject: @my-project/demo-api-backend
- Haga clic en
Generate
pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend
yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend
npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend
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 nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend --dry-run
yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend --dry-run
npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api-backend --dry-run
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
- Instale el Nx Console VSCode Plugin si aún no lo ha hecho
- Abra la consola Nx en VSCode
- Haga clic en
Generate (UI)
en la sección "Common Nx Commands" - Busque
@aws/nx-plugin - ts#infra
- Complete los parámetros requeridos
- name: infra
- Haga clic en
Generate
pnpm nx g @aws/nx-plugin:ts#infra --name=infra
yarn nx g @aws/nx-plugin:ts#infra --name=infra
npx nx g @aws/nx-plugin:ts#infra --name=infra
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 nx g @aws/nx-plugin:ts#infra --name=infra --dry-run
yarn nx g @aws/nx-plugin:ts#infra --name=infra --dry-run
npx nx g @aws/nx-plugin:ts#infra --name=infra --dry-run
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 4: 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'); api.grantInvokeAccess(identity.identityPool.authenticatedRole);
new DemoWebsite(this, 'website'); }}
Esto es todo el código 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 nx run-many --target build --all
yarn nx run-many --target build --all
npx nx run-many --target build --all
bunx nx run-many --target build --all
Paso 5: Ejecutar el Frontend Localmente
-
Obtén el archivo
runtime-config.json
:Terminal window pnpm nx run @demo/demo-website:load:runtime-configTerminal window yarn nx run @demo/demo-website:load:runtime-configTerminal window npx nx run @demo/demo-website:load:runtime-configTerminal window bunx nx run @demo/demo-website:load:runtime-config -
Inicia el servidor local del sitio web
Terminal window pnpm nx run @demo/demo-website:serveTerminal window yarn nx run @demo/demo-website:serveTerminal window npx nx run @demo/demo-website:serveTerminal window bunx nx run @demo/demo-website:serve
Tu sitio web estará disponible en http://localhost:4200
.
¡Felicidades! 🎉 ¡Has construido y desplegado exitosamente una aplicación full-stack usando @aws/nx-plugin
!