Agregar a un Proyecto Existente

No todos los proyectos comienzan con pnpm create @aws/nx-workspace. Si ya tienes un espacio de trabajo Nx — o un monorepo al que puedes agregar Nx — puedes adoptar @aws/nx-plugin de forma incremental sin recrear tu proyecto.

Consejo

Puedes usar tu herramienta de codificación agéntica de preferencia para agregar el plugin por ti, usando el servidor MCP. Prueba el prompt:

Add the Nx Plugin for AWS to this project.

Prerrequisitos

Requeridos

• Git
• Node >= 22 (Recomendamos usar algo como NVM para gestionar tus versiones de node)
  • verifica ejecutando node --version
• UV >= 0.5.29
  1. instala Python 3.14 ejecutando: uv python install 3.14.0
  2. verifica con uv python list --only-installed

Recomendados

• PNPM >= 11 (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
• AWS Credentials configuradas para tu cuenta de AWS de destino son necesarias para desplegar tu aplicación (así como para algunos flujos de trabajo de desarrollo local).
• Docker o Finch >= 1.6.0 es necesario para algunos generadores. Para Docker, las compilaciones multiplataforma deben estar configuradas; Finch soporta compilaciones multiplataforma de forma predeterminada.
• Terraform >= 1.12 es necesario si eliges usar esto para infraestructura como código en lugar de CDK
  • verifica ejecutando terraform --version
• Si estás usando VSCode, recomendamos instalar el Nx Console VSCode Plugin.

Configuración del Asistente de IA

Si utilizas un Asistente de IA como Kiro, Kiro CLI, Cursor, Claude Code o Cline, es posible que también desees instalar el servidor MCP de Nx Plugin for AWS.

Antes de comenzar

Guarda y confirma todo el trabajo en progreso primero, para que los cambios realizados en cada paso puedan ser revisados — y revertidos — en cualquier momento.

Agregar Nx a un proyecto no-Nx

Si tu proyecto aún no usa Nx, agrégalo primero con nx init. Este es un paso que Nx mismo posee; el plugin se construye sobre un espacio de trabajo Nx funcional. Funciona en un paquete simple, un espacio de trabajo npm/pnpm/yarn/bun, un monorepo Turborepo o Lerna:

pnpm

pnpm dlx nx@23.1.1 init

yarn

yarn dlx nx@23.1.1 init

npm

npx nx@23.1.1 init

bun

bunx nx@23.1.1 init

Sigue las indicaciones para agregar Nx a tu espacio de trabajo. Para más detalles consulta la Documentación de Nx.

pnpm workspaces

pnpm solo ejecuta scripts de instalación para paquetes en la lista de permitidos, y nx necesita su script de instalación — sin él, la instalación que realiza nx init puede fallar, dejando un marcador de posición set this to true or false en pnpm-workspace.yaml. Agrégalo a la lista de permitidos antes de ejecutar nx init:

pnpm-workspace.yaml

allowBuilds:
  - nx

Proyectos no-Node (Python, Go, Java, Rust, …)

Nx y el plugin se distribuyen como paquetes npm, por lo que un proyecto sin herramientas Node.js necesita un package.json raíz mínimo antes de que nx init pueda hacer algo útil:

package.json

{
  "name": "my-project",
  "private": true,
  "type": "module"
}

Crea ese archivo, luego ejecuta nx init y agrega el plugin como de costumbre. Tus herramientas de lenguaje existentes no se tocan — los proyectos Nx generados por el plugin (incluyendo proyectos Python) viven junto a tu código existente, y puedes conectar tu compilación existente a Nx de forma incremental.

Para traer tus proyectos existentes bajo Nx, tienes algunas opciones dependiendo del lenguaje:

• Lenguajes con un plugin oficial de Nx — Java (Gradle o Maven) y .NET tienen plugins dedicados que infieren las tareas de tus proyectos automáticamente. Agrega el relevante, por ejemplo nx add @nx/gradle, nx add @nx/maven o nx add @nx/dotnet.
• Lenguajes con un plugin de la comunidad — por ejemplo Go (@nx-go/nx-go) o Rust (@monodon/rust). Explora el Registro de Plugins de Nx para otros.
• Cualquier otro lenguaje — agrega un project.json a cada proyecto y define sus targets para ejecutar tus comandos de compilación existentes, para que nx build <project> (y nx run-many) los ejecuten. Consulta la guía del espacio de trabajo para ver cómo se configuran project.json y los targets.

Proyectos de un solo paquete

El plugin está diseñado para monorepos — genera cada proyecto en su propio directorio bajo packages/. Si estás comenzando desde un proyecto de un solo paquete (un package.json en la raíz con tu código fuente directamente debajo, sin espacios de trabajo), mueve tu paquete existente a packages/ antes de adoptar el plugin para que tu proyecto se ubique junto a los que genera el plugin:

1. Crea un directorio packages/<tu-paquete>/ y mueve tu código fuente, package.json y tsconfig.json dentro de él.

2. Crea un nuevo package.json raíz que actúe como el manifiesto del espacio de trabajo en lugar de un proyecto en sí:

   package.json

   {
     "name": "<your-workspace>",
     "private": true,
     "type": "module"
   }

3. Declara el espacio de trabajo para que tu gestor de paquetes descubra proyectos bajo packages/. Para pnpm, agrega un pnpm-workspace.yaml:

   pnpm-workspace.yaml

   packages:
     - packages/*

   Para npm/yarn/bun, agrega un campo workspaces al package.json raíz en su lugar:

   package.json

   {
     "workspaces": ["packages/*"]
   }

4. Ejecuta nx init (si no lo has hecho), luego agrega el plugin.

Gestor de paquetes

Los proyectos del plugin se generan bajo un directorio packages/. pnpm lee los globs del espacio de trabajo desde pnpm-workspace.yaml; otros gestores de paquetes leen el campo workspaces del package.json raíz — init actualiza el que use tu espacio de trabajo.

Agregar el plugin

Usa nx add, que instala el plugin en una versión compatible con tu instalación de Nx y luego ejecuta su generador init para configurar tu espacio de trabajo:

pnpm

pnpm nx add @aws/nx-plugin

yarn

yarn nx add @aws/nx-plugin

npm

npx nx add @aws/nx-plugin

bun

bunx nx add @aws/nx-plugin

Una vez que se complete, tu espacio de trabajo está listo — elige los generadores que necesites y comienza a generar proyectos.

Qué configura este generador

Agregar el plugin realiza los cambios determinísticos que un espacio de trabajo necesita para ejecutar los generadores del plugin. Preserva el formato de módulo de tu espacio de trabajo: un espacio de trabajo cuyo package.json raíz tiene type: "module" permanece ESM, cualquier otra cosa permanece CommonJS, y el código generado sigue el mismo patrón. No sobrescribe archivos existentes, y es posible que necesites hacer algunos cambios manuales después de este paso dependiendo de tu configuración existente.

Crea o actualiza los siguientes archivos:

• aws-nx-plugin.config.mts registra tu proveedor de IaC elegido (CDK o Terraform) y motor de contenedores; los generadores leen iac.provider desde aquí
• nx.json registra los generadores de sincronización (@nx/js:typescript-sync y @aws/nx-plugin:ts#sync) en el target compile para que las referencias de proyecto TypeScript permanezcan sincronizadas
• tsconfig.json una configuración TypeScript raíz que referencia los proyectos de tu espacio de trabajo, que la sincronización TypeScript de Nx mantiene actualizada
• tsconfig.base.json las opciones de compilador compartidas que los proyectos TypeScript del plugin extienden (ver abajo para lo que contiene)
• pnpm-workspace.yaml (solo pnpm) lista de permitidos de los scripts de compilación que las dependencias del plugin necesitan (@swc/core, esbuild, nx, sharp)
• package.json scripts de conveniencia para tareas comunes, más las dependencias de desarrollo @aws/nx-plugin, @aws/nx-plugin-mcp, nx, @nx/js, @nx/workspace, typescript y Biome
• biome.json configuración predeterminada del formateador y linter Biome
• .mcp.json configura el servidor MCP para agentes de codificación compatibles a menos que se deshabilite (también equivalentes .cursor/, .kiro/, .gemini/, .vscode/ y .codex/). Ejecuta el propio @aws/nx-plugin-mcp del espacio de trabajo, por lo que el servidor siempre coincide con la versión instalada en tu espacio de trabajo

La configuración del servidor MCP se puede deshabilitar con --mcp=false.

Haz clic aquí para ver las opciones de compilador que lleva un tsconfig.base.json creado.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
iac	cdk | terraform	cdk	El proveedor de IaC preferido.
mcp	boolean	true	Si se debe configurar el Nx Plugin para el servidor AWS MCP para uso por agentes de codificación.
containers	infer | docker | finch	infer	El motor de contenedores a utilizar para build/push/login. 'infer' selecciona docker si está instalado, de lo contrario finch (recurriendo a docker cuando ninguno está instalado).
preferInstallDependencies	boolean	true	Si se prefiere instalar dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al procesar múltiples generadores en lote (la instalación aún se ejecuta si es necesaria para que los generadores subsecuentes puedan calcular el grafo de proyecto de Nx); instalar una vez al final.

Solución de problemas

nx build <project> ya no funciona para una biblioteca TypeScript existente

La primera ejecución de ts#project configura el plugin @nx/js/typescript para inferir el target de compilación TypeScript como compile (el plugin reserva build para orquestar lint, compile y test). Las bibliotecas existentes que dependen del target inferido build también se infieren como compile — ejecuta nx run <project>:compile, o usa nx run-many --target build,compile. Las bibliotecas con un target build explícito en su project.json no se ven afectadas.

The workspace is out of sync

Las referencias de proyecto TypeScript necesitan sincronización. init registra los generadores de sincronización; ejecuta:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

ERR_PNPM_IGNORED_BUILDS durante la instalación

pnpm omite scripts de instalación para paquetes que no están en la lista de permitidos. init agrega a la lista de permitidos los que las herramientas del plugin necesitan (@swc/core, esbuild, nx, sharp) en pnpm-workspace.yaml, pero el bloqueo puede activarse durante nx add @aws/nx-plugin mismo — antes de que init se haya ejecutado. Ejecuta pnpm approve-builds y aprueba los paquetes listados (o agrégalos bajo allowBuilds:), luego vuelve a ejecutar la instalación.

nx sync se cuelga, o plugin worker ... exited before the connection was established

Si dos versiones diferentes de nx están presentes en el mismo árbol node_modules (ejecuta npm ls nx para confirmar), su IPC de plugin-worker entra en deadlock. El generador init fija la devDependency nx raíz a la versión que resuelven los propios paquetes @nx/* del plugin, pero una instalación posterior de otro paquete @nx/* en una versión de parche diferente puede reintroducir la discrepancia. Alinea cada entrada nx y @nx/* en tu package.json raíz a una sola versión y reinstala.

ts.readConfigFile is not a function

Tu espacio de trabajo tiene TypeScript 7 instalado, que Nx aún no soporta — los plugins de Nx dependen de la API de compilador en proceso de TypeScript, que TypeScript 7 ya no proporciona. Fija typescript en tu package.json raíz a la versión que usa el plugin (el generador init instala una versión compatible) y reinstala.

Recursive task invocation detected

Tu package.json raíz está registrado como un proyecto Nx (tiene una clave "nx", que nx init agrega para un repositorio de un solo paquete) y lleva un script build de nx run-many --target build. Nx entonces infiere un target build en la raíz que se llama a sí mismo. Mueve tu código fuente a packages/<tu-paquete>/ para que la raíz se convierta en un manifiesto del espacio de trabajo en lugar de un proyecto — consulta Proyectos de un solo paquete. (Los propios presets independientes de Nx evitan esto estableciendo "nx": { "includedScripts": [] } en el paquete raíz; puedes hacer lo mismo como una alternativa más rápida.)

Errores de TypeScript en tus proyectos existentes después de agregar el plugin (TS6059, TS7016, TS5011, NG4006)

Los propios proyectos generados del plugin llevan las configuraciones TypeScript que necesitan en su tsconfig.lib.json por proyecto, por lo que se compilan independientemente de tu tsconfig.base.json. Estos errores aparecen en cambio en un proyecto preexistente tuyo que hereda un tsconfig.base.json que init creó (con composite/emitDeclarationOnly/nodenext) pero no es compatible con esas configuraciones — por ejemplo, el compilador Angular rechaza emitDeclarationOnly (NG4006), o un proyecto que establece outDir sin un rootDir ahora necesita uno (TS5011). Agrega sobrescrituras de tsconfig por proyecto redeclarando las opciones conflictivas para esos proyectos (por ejemplo "rootDir": "src"), o apunta los proyectos del plugin y tus proyectos a configuraciones base separadas.

init nunca reescribe un tsconfig.base.json existente, precisamente para que no pueda romper silenciosamente los proyectos que heredan de él — resolver estas discrepancias es una decisión que solo tú puedes tomar para tu código base.

ESM y CommonJS

El formato de módulo es a nivel de espacio de trabajo, leído del campo type del package.json raíz: type: "module" significa ESM, cualquier otra cosa (incluyendo ningún campo type) significa CommonJS. init preserva el que use tu espacio de trabajo, y los generadores TypeScript del plugin emiten código coincidente. Si más tarde quieres cambiar, cambia el type raíz — pero esa es una migración de tu código existente, no algo que init haga por ti.