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.
Requisitos previos
Sección titulada «Requisitos previos»Se necesitan las siguientes dependencias globales antes de continuar:
Requeridos
Sección titulada «Requeridos»- Git
- Node >= 22 (Recomendamos usar algo 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:
- Credenciales de AWS configuradas para tu cuenta objetivo de AWS (donde se desplegará tu aplicación)
Recomendados
Sección titulada «Recomendados»- Docker es requerido para algunos generadores.
- Terraform >= 1.12 es necesario si eliges usarlo para infraestructura como código en lugar de CDK
- Verifica ejecutando
terraform --version
- Verifica ejecutando
- Si usas VSCode, recomendamos instalar el Plugin Nx Console para VSCode.
Paso 1: Inicializar un nuevo espacio de trabajo Nx
Sección titulada «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@21.4.1 my-project --pm=pnpm --preset=@aws/nx-plugin --ci=skip
npx create-nx-workspace@21.4.1 my-project --pm=yarn --preset=@aws/nx-plugin --ci=skip
npx create-nx-workspace@21.4.1 my-project --pm=npm --preset=@aws/nx-plugin --ci=skip
npx create-nx-workspace@21.4.1 my-project --pm=bun --preset=@aws/nx-plugin --ci=skip
Una vez completado, accede al directorio del proyecto:
cd my-project
Paso 2: Usar generadores para estructurar tu proyecto
Sección titulada «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
Sección titulada «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
- name: demo-api
- auth: IAM
- Haga clic en
Generate
pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM
yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM
npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM
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 nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run
yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run
npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run
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
Sección titulada «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#react-website
- Complete los parámetros requeridos
- name: demo-website
- Haga clic en
Generate
pnpm nx g @aws/nx-plugin:ts#react-website --name=demo-website
yarn nx g @aws/nx-plugin:ts#react-website --name=demo-website
npx nx g @aws/nx-plugin:ts#react-website --name=demo-website
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 nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run
yarn nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run
npx nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run
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
Sección titulada «Agregar autenticación 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#react-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#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
yarn nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
npx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo
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 nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
yarn nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
npx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run
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
Sección titulada «Conectar el frontend al 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
- Haga clic en
Generate
pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api
yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api
npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api
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 nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run
yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run
npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run
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
Sección titulada «Agregar infraestructura»Agrega el proyecto de infraestructura según tu proveedor IaC elegido.
- 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.
- 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 - terraform#project
- Complete los parámetros requeridos
- name: infra
- Haga clic en
Generate
pnpm nx g @aws/nx-plugin:terraform#project --name=infra
yarn nx g @aws/nx-plugin:terraform#project --name=infra
npx nx g @aws/nx-plugin:terraform#project --name=infra
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 nx g @aws/nx-plugin:terraform#project --name=infra --dry-run
yarn nx g @aws/nx-plugin:terraform#project --name=infra --dry-run
npx nx g @aws/nx-plugin:terraform#project --name=infra --dry-run
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
Sección titulada «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 nx run demo-website:serve-local
yarn nx run demo-website:serve-local
npx nx run demo-website:serve-local
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
Sección titulada «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', { 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.
Abre packages/infra/src/main.tf
y agrega el siguiente código:
# Include metrics tracking for @aws/nx-plugin usagemodule "metrics" { source = "../../common/terraform/src/metrics"}
# Deploy user identitymodule "user_identity" { source = "../../common/terraform/src/core/user-identity"}
# Deploy APImodule "demo_api" { source = "../../common/terraform/src/app/apis/demo-api"}
# Grant authenticated users access to invoke the APIresource "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 websiteprovider "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
Sección titulada «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
Inicializa tu infraestructura:
pnpm nx run infra:bootstrap
yarn nx run infra:bootstrap
npx nx run infra:bootstrap
bunx nx run infra:bootstrap
pnpm nx run infra:bootstrap
yarn nx run infra:bootstrap
npx nx run infra:bootstrap
bunx nx run infra:bootstrap
Despliega tu proyecto:
pnpm nx run infra:deploy my-project-sandbox/*
yarn nx run infra:deploy my-project-sandbox/*
npx nx run infra:deploy my-project-sandbox/*
bunx nx run infra:deploy my-project-sandbox/*
pnpm nx run infra:apply
yarn nx run infra:apply
npx nx run infra:apply
bunx nx run infra:apply
Paso 5: Probar el sitio web con los recursos en la nube desplegados
Sección titulada «Paso 5: Probar el sitio web con los recursos en la nube desplegados»-
Obtén el archivo
runtime-config.json
:Terminal window pnpm nx run demo-website:load:runtime-configTerminal window yarn nx run demo-website:load:runtime-configTerminal window npx nx run demo-website:load:runtime-configTerminal window bunx nx run demo-website:load:runtime-config -
Inicia el servidor local del sitio web
Terminal window pnpm nx run demo-website:serveTerminal window yarn nx run demo-website:serveTerminal window npx nx run demo-website:serveTerminal window 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
!