Espacio de trabajo

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

Crear un espacio de trabajo

pnpm create @aws/nx-workspace my-project

yarn create @aws/nx-workspace my-project

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

bun create @aws/nx-workspace my-project

Opciones

Parámetro	Tipo	Predeterminado	Descripción
addTsPlugin	boolean	true	Si se debe agregar el plugin de ts.
iacProvider	string	CDK	El proveedor de IaC preferido.
gitSecrets	boolean	true	Si se debe configurar git-secrets para prevenir el commit de credenciales de AWS.
containerEngine	string	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).

Estructura del espacio de trabajo

Directoriopackages/ Tus proyectos viven aquí
- …
package.json package.json raíz para tu monorepo
nx.json Configuración de Nx (targets comunes, generadores de sincronización, caché)
tsconfig.base.json Configuración raíz de TypeScript
aws-nx-plugin.config.mts Configuración del Nx Plugin for AWS
Directorio.git-secrets/ Script bash de git-secrets incluido para escaneo de credenciales
- …
Directorio.husky/ Hooks de Git
- …

Nx

Nx es un sistema de construcción agnóstico del lenguaje para monorepos, que gestiona 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 entre proyectos.

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

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

Para detalles sobre cómo se configuran los proyectos de TypeScript y Python, consulta las guías de 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 un comportamiento obsoleto o inesperado, reinicia la caché con:

pnpm nx reset

yarn nx reset

npx nx reset

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 archivo de bloqueo en la raíz con un único node_modules que contiene todas las dependencias. Si necesitas agregar una nueva dependencia, agrégala en el package.json raíz.

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 espacio de trabajo UV y posteriormente escritas en el archivo uv.lock en la raíz.

Comandos comunes

Build

Construir todos los proyectos en el espacio de trabajo:

pnpm build

yarn build

npm run build

bun build

Lint

Lint y auto-corrección de todos los proyectos:

pnpm lint

yarn lint

npm run lint

bun lint

Test

Ejecutar pruebas en todos los proyectos:

pnpm test

yarn test

npm run test

bun test

Dev

Si tienes un sitio web, inícialo junto con todos los componentes conectados localmente:

pnpm dev

yarn dev

npm run dev

bun dev

Sync

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

pnpm nx sync

yarn nx sync

npx nx sync

bunx nx sync

Ejecutar targets específicos

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

pnpm nx <target> <project>

yarn nx <target> <project>

npx nx <target> <project>

bunx nx <target> <project>

Por ejemplo:

pnpm nx build website

yarn nx build website

npx nx build website

bunx nx build website

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

Qué está incluido

Linting

Los nuevos espacios de trabajo están configurados con ESLint para análisis estático y Prettier para formateo de código. Ejecutar lint aplica ambos a todos los proyectos.

Git Secrets

Los nuevos espacios de trabajo incluyen hooks de pre-commit de git-secrets que escanean archivos preparados en busca de patrones de credenciales de AWS antes de cada commit. Esto previene el commit 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:

# Permitir un patrón regex específico
git secrets --add --allowed 'my-regex-pattern'

# Permitir una cadena literal (los caracteres especiales se escapan)
git secrets --add --allowed --literal 'my-literal+string'

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

# 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 espacio de trabajo incluye un archivo aws-nx-plugin.config.mts en la raíz. Los generadores leen este archivo para elegir valores predeterminados sensatos, de modo 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#trpc-api, py#fast-api). Los generadores que aceptan una bandera --iacProvider tienen como valor predeterminado Inherit, que lee este valor.
containers.engine — la CLI de contenedores (docker o finch) integrada en los comandos generados de build/push/login. Las construcciones de image-asset de CDK también toman 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 tomarán el nuevo valor.