Workspace

Cuando creas un nuevo workspace con @aws/nx-plugin, el generador preset configura un monorepo de Nx con valores predeterminados sensatos para construir en AWS.

Crear un Workspace

pnpm

pnpm create @aws/nx-workspace my-project

yarn

yarn create @aws/nx-workspace my-project

npm

npm create @aws/nx-workspace -- my-project

bun

bun create @aws/nx-workspace my-project

Opciones

Parámetro	Tipo	Predeterminado	Descripción
iac	cdk | terraform	cdk	El proveedor de IaC preferido.
gitSecrets	boolean	true	Si se debe configurar git-secrets para prevenir el commit de credenciales de AWS.
mcp	boolean	true	Si se debe configurar el Nx Plugin para el servidor AWS MCP para uso de 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).
module	esm | cjs	esm	Formato de módulo para el código TypeScript y la configuración generados.
catalog	boolean	true	Si los generadores registran las versiones de dependencias en el catálogo del gestor de paquetes (pnpm/yarn/bun), manteniendo una única fuente de verdad para las versiones. Cuando es false, las dependencias se escriben directamente en el package.json de cada proyecto y mantener las versiones alineadas es tu responsabilidad.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Estructura del Workspace

• Directoriopackages/ Your projects live here

  • …
• package.json Root package.json for your monorepo
• nx.json Nx configuration (common targets, sync generators, caching)
• tsconfig.base.json Root TypeScript configuration
• aws-nx-plugin.config.mts Nx Plugin for AWS configuration
• Directorio.git-secrets/ Vendored git-secrets bash script for credential scanning

  • …
• Directorio.husky/ Git hooks

  • …
• .mcp.json Nx Plugin for AWS MCP server configuration for Claude Code
• .cursor/mcp.json …and for Cursor
• .kiro/settings/mcp.json …and for Kiro
• .gemini/settings.json …and for Gemini CLI
• .vscode/mcp.json …and for GitHub Copilot
• .codex/config.toml …and for OpenAI Codex

Nx

Nx es un sistema de construcción agnóstico del lenguaje para monorepos, que gestiona las dependencias entre proyectos escritos en cualquier lenguaje de programación y las tareas para construirlos. Puedes aprender más en el sitio web de Nx.

Proyectos

Un monorepo de Nx está compuesto por uno o más proyectos, cada uno con un archivo project.json. El project.json define las tareas de un proyecto, conocidas como targets, que definen cómo se construye un proyecto, se ejecuta localmente, se prueba, etc. También define dependencias entre targets dentro o a través de proyectos.

Por ejemplo, un project.json podría definir un target build que depende de que todos los proyectos upstream se construyan primero:

packages/my-project/project.json

{
  "name": "@my-workspace/my-project",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "dependsOn": ["^build"]
    },
    "test": {
      "command": "vitest run"
    }
  }
}

Consejo

Para proyectos en lenguajes no soportados directamente por el Nx Plugin for AWS, a menudo puedes encontrar un generador en el Nx Plugin Registry para ayudar. Sin embargo, es simple agregar un proyecto de cualquier lenguaje a tu monorepo — solo agrega un archivo project.json y define su target build para ejecutar el comando de construcción específico para un proyecto de ese lenguaje.

Para detalles sobre cómo se configuran los proyectos de TypeScript y Python, consulta las guías de los generadores ts#project y py#project.

Caché

Nx almacena en caché la salida de targets ejecutados previamente y los reproduce cuando las entradas no han cambiado. Esto acelera dramáticamente las construcciones, pruebas y linting — especialmente en CI. Si encuentras comportamiento obsoleto o inesperado, reinicia la caché con:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Para más detalles, consulta la documentación de caché de Nx.

Política de Versión Única

La configuración predeterminada del monorepo usa una política de versión única tanto para proyectos basados en Node como en Python.

Esto significa que todos los proyectos dentro de tu monorepo usan la misma versión de dependencias por defecto, reduciendo problemas relacionados con paquetes en el mismo monorepo que encuentran problemas de desajuste de versiones.

Desde una perspectiva de Node, esto significa un único lockfile en la raíz, con dependencias instaladas una vez y enlazadas en cada proyecto. Cada proyecto de Node declara las dependencias de tiempo de ejecución que su código fuente importa en su propio package.json, mientras que las herramientas compartidas de construcción/prueba viven en el package.json raíz en devDependencies. Agrega una dependencia de tiempo de ejecución de un proyecto instalándola en ese proyecto:

pnpm

pnpm add some-npm-package --filter my-project

yarn

yarn workspace @my-scope/my-project add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package -w packages/my-project

bun

bun add some-npm-package --cwd packages/my-project

Para gestores de paquetes con soporte de catálogo (pnpm, yarn y bun), las versiones de dependencias se registran en el catálogo y se referencian con el protocolo catalog:, manteniendo una única fuente de verdad para las versiones en el package.json de cada proyecto. Para npm workspaces, recomendamos syncpack para alinear las versiones declaradas en múltiples archivos package.json.

Desde una perspectiva de Python, esto significa un único .venv en la raíz del monorepo con todas las dependencias instaladas en él. Cada proyecto de Python tiene su propio pyproject.toml, pero las versiones de esas dependencias son gestionadas por el workspace de UV y posteriormente escritas en el archivo uv.lock en la raíz.

Comandos Comunes

Build

Construir todos los proyectos en el workspace:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Lint

Hacer lint y auto-corregir todos los proyectos:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Test

Ejecutar pruebas en todos los proyectos:

pnpm

pnpm test

yarn

yarn test

npm

npm run test

bun

bun test

Dev

Iniciar todos los servidores de desarrollo local en tu workspace:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Consulta la guía de Desarrollo Local para más detalles.

Sync

Ejecutar cualquier generador de sincronización, que por ejemplo sincronizan las referencias de proyectos de TypeScript (consulta la guía del generador ts#project para más detalles):

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Ejecutar Targets Específicos

Puedes ejecutar targets específicos para proyectos específicos con:

pnpm

pnpm nx <target> <project>

yarn

yarn nx <target> <project>

npm

npx nx <target> <project>

bun

bunx nx <target> <project>

Por ejemplo:

pnpm

pnpm nx build website

yarn

yarn nx build website

npm

npx nx build website

bun

bunx nx build website

Esto ejecutará el target elegido así como los targets de los que depende.

Qué Está Incluido

Linting

Los nuevos workspaces están configurados con Biome para análisis estático y formateo de código. Ejecutar lint verifica todos los proyectos en busca de problemas, y lint --configuration=fix los auto-corrige.

Git Secrets

Los nuevos workspaces incluyen hooks pre-commit de git-secrets que escanean archivos preparados en busca de patrones de credenciales de AWS antes de cada commit. Esto previene la confirmación accidental de claves de acceso, claves secretas y otros valores sensibles.

Suprimir Falsos Positivos

Los patrones en git-secrets usan expresiones regulares compatibles con egrep. Si git-secrets bloquea un commit que no contiene credenciales reales:

# Allow a specific regex pattern
git secrets --add --allowed 'my-regex-pattern'

# Allow a literal string (special characters are escaped)
git secrets --add --allowed --literal 'my-literal+string'

También puedes crear un archivo .gitallowed en la raíz del repositorio con una regex compatible con egrep por línea (compartida con tu equipo a través del control de versiones):

.gitallowed

# Allow test fixtures
tests/fixtures/.*
# Allow a specific string
EXAMPLE[A-Z]{16}

Para detalles completos sobre la gestión de patrones, consulta la documentación de git-secrets.

Configuración del Nx Plugin for AWS

El workspace viene con un archivo aws-nx-plugin.config.mts en la raíz. Los generadores leen este archivo para elegir valores predeterminados sensatos para que no tengas que pasar las mismas banderas cada vez. Dos configuraciones son particularmente útiles:

// aws-nx-plugin.config.mts
import { AwsNxPluginConfig } from '@aws/nx-plugin';

export default {
  iac: {
    provider: 'cdk', // or 'terraform'
  },
  containers: {
    engine: 'docker', // or 'finch'
  },
} satisfies AwsNxPluginConfig;

• iac.provider — el proveedor de infraestructura como código predeterminado (cdk o terraform) utilizado por los generadores que emiten infraestructura (por ejemplo, ts#infra, ts#api, py#api). Los generadores que aceptan una bandera --iac tienen como valor predeterminado inherit, que lee este valor.
• containers.engine — la CLI de contenedores (docker o finch) incorporada en los comandos generados de build/push/login. Las construcciones de image-asset de CDK también recogen esto a través de la variable de entorno CDK_DOCKER. Consulta la guía de empaquetado de Docker para más detalles.

Puedes editar cualquiera de estas configuraciones en cualquier momento — las ejecuciones posteriores del generador recogerán el nuevo valor.