Claude Code y Nx Workspace: guía práctica de monorepos
Aprende a usar Claude Code con Nx Workspace: límites, nx graph, affected CI, caché y errores comunes.
Nx Workspace no es un repositorio gigante: es un mapa de límites
Si le pides a Claude Code “crea un monorepo”, probablemente generará muchos archivos. El problema aparece después: ¿un cambio en apps/web puede romper apps/admin? ¿Un botón debe vivir dentro de la app o en una librería UI compartida? ¿CI debe ejecutar todas las pruebas en cada pull request?
Nx Workspace responde con project graph, task graph, comandos affected y caché. El modelo mental oficial de Nx explica cómo Nx analiza proyectos y ejecuta solo el trabajo necesario. Para principiantes, piensa en Nx como un mapa de dependencias más un ejecutor de tareas.
En esta guía usamos Claude Code como revisor y compañero de implementación, no como generador sin control. Mantén abiertas estas referencias oficiales: create-nx-workspace, workspace generators, affected, CI setup y caching tasks. Para contexto adicional, lee gestión de monorepos con Claude Code, pnpm workspace y CI/CD setup.
Cuándo sí merece la pena usar Nx
Nx no es obligatorio para todos los proyectos. Una landing y una API pequeña pueden vivir mejor en un repositorio simple. Nx empieza a compensar cuando los límites y el coste de verificación se vuelven visibles.
Primer caso real: varias aplicaciones comparten tipos o UI. Puedes tener apps/web, apps/admin, apps/api, libs/contracts y libs/ui en el mismo repo para actualizar tipos de API y componentes base en un solo PR.
Segundo caso: CI selectivo. Si el sitio de contenido, las páginas de formación, el panel interno y la API comparten repo, ejecutar todo en cada PR es lento. nx affected -t test build usa los cambios de Git y el grafo de dependencias para elegir solo los proyectos afectados.
Tercer caso: hacer más seguro a Claude Code. Si defines libs/ui como UI pura, libs/contracts como tipos de API, libs/config como configuración compartida y apps/* como aplicaciones desplegables, Claude Code tiene menos margen para refactorizar de más. Esto importa en páginas con AdSense, afiliados, formularios de consulta o CTAs de pago.
Si todavía no puedes explicar tus límites, empieza con repo map first pass. Nx acelera una estructura clara; no arregla mágicamente una estructura confusa.
Estructura objetivo
La guía usa una estructura pequeña: dos apps React, una API Node, una librería UI, una librería de contratos y una librería de configuración.
flowchart LR
web["apps/web\nReact + Vite"] --> ui["libs/ui\nUI primitives"]
admin["apps/admin\nReact + Vite"] --> ui
web --> contracts["libs/contracts\nAPI types"]
admin --> contracts
api["apps/api\nNode API"] --> contracts
web --> config["libs/config\nlint/test config"]
api --> config
La regla es sencilla: apps/* son unidades que se ejecutan o despliegan; libs/* son piezas reutilizables. Una librería no debe importar desde una app. Una librería UI no debe leer variables de entorno de la API, y una librería de contratos no debe contener componentes React.
Pásale este contexto a Claude Code antes de pedir cambios:
Primero entiende este Nx Workspace. No edites todavía.
Reglas:
- apps/web y apps/admin son aplicaciones frontend
- apps/api es la API
- libs/ui contiene solo componentes visuales reutilizables
- libs/contracts contiene tipos de API y Zod schemas
- libs/config contiene configuración compartida de ESLint, Vitest y TypeScript
- libs/* no debe importar desde apps/*
Antes de cambiar, revisa nx graph. Después, da los comandos nx affected necesarios para verificar.
Setup copiable
Asumo Node.js 20+, Git y pnpm. Uso opciones explícitas para evitar diferencias por prompts interactivos.
npx create-nx-workspace@latest acme-nx \
--workspaceType=integrated \
--preset=apps \
--packageManager=pnpm \
--nxCloud=skip \
--interactive=false
cd acme-nx
pnpm nx add @nx/react
pnpm nx add @nx/node
Genera apps y librerías con los generators de Nx. Son mejores que crear carpetas a mano porque actualizan configuración de Nx, paths de TypeScript y metadatos del proyecto.
pnpm nx g @nx/react:app web \
--directory=apps/web \
--bundler=vite \
--unitTestRunner=vitest \
--e2eTestRunner=playwright \
--style=css
pnpm nx g @nx/react:app admin \
--directory=apps/admin \
--bundler=vite \
--unitTestRunner=vitest \
--e2eTestRunner=none \
--style=css
pnpm nx g @nx/node:app api \
--directory=apps/api \
--unitTestRunner=vitest
pnpm nx g @nx/react:lib ui \
--directory=libs/ui \
--unitTestRunner=vitest
pnpm nx g @nx/js:lib contracts \
--directory=libs/contracts \
--unitTestRunner=vitest
pnpm nx g @nx/js:lib config \
--directory=libs/config \
--unitTestRunner=none
Antes de editar, mira el resultado:
pnpm nx graph
pnpm nx show projects
pnpm nx show project web
Si el grafo ya parece enredado, simplifica antes de crear más librerías.
Lee project.json antes de tocarlo
Para principiantes, project.json es la lista de tareas que puede ejecutar un proyecto.
{
"name": "web",
"sourceRoot": "apps/web/src",
"projectType": "application",
"targets": {
"build": {
"executor": "@nx/vite:build",
"outputs": ["{options.outputPath}"],
"options": {
"outputPath": "dist/apps/web"
}
},
"test": {
"executor": "@nx/vite:test",
"outputs": ["{workspaceRoot}/coverage/apps/web"],
"options": {
"passWithNoTests": true
}
},
"serve": {
"executor": "@nx/vite:dev-server",
"options": {
"buildTarget": "web:build"
}
}
},
"tags": ["scope:app", "type:web"]
}
Pide explicación antes de permitir cambios:
Lee apps/web/project.json y explica build, test y serve para una persona principiante.
Si hace falta cambiar algo, propón solo el diff mínimo.
No rompas outputs, caché ni relaciones dependsOn.
outputs es importante porque Nx lo usa para cachear artefactos. Una ruta incorrecta puede inutilizar la caché o reutilizar resultados viejos.
affected en CI
affected compara cambios de Git con el grafo del proyecto y ejecuta tareas solo donde puede haber impacto.
pnpm nx affected -t lint test build --base=main --head=HEAD
pnpm nx affected:graph --base=main --head=HEAD
En GitHub Actions, usa historial completo para que Nx pueda comparar ramas. Ejecuta tareas mediante nx; llamar directamente a vitest, eslint o tsc evita la lógica affected y la caché de Nx.
name: nx-ci
on:
pull_request:
push:
branches: [main]
jobs:
affected:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: pnpm/action-setup@v4
with:
version: 10
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm nx affected -t lint test build --base=origin/main --head=HEAD --parallel=3
Cuando el equipo crece, Nx Cloud puede reducir trabajo repetido en CI. Primero demuestra valor con caché local y affected; después añade caché remota si el tiempo de CI ya duele.
Errores frecuentes
El primer error es crear libs/shared y meter todo ahí. Antes de mover código, haz que Claude Code lo clasifique como UI, contracts, config o utilidad pura.
El segundo es importar desde apps/* dentro de libs/*. Eso invierte la dirección de dependencia y destruye la reutilización.
El tercero es ejecutar herramientas crudas en CI. Prefiere pnpm nx run-many -t test o pnpm nx affected -t test.
El cuarto es sobrediseñar la primera semana. No crees libs/auth, libs/domain y libs/data-access antes de tener duplicación real.
El quinto es dejar que Claude Code edite sin contexto del grafo. Incluye siempre pnpm nx graph antes y pnpm nx affected -t test build después.
Monetización: protege las páginas que generan ingresos
En un sitio como ClaudeCodeLab, artículos, páginas de formación, admin, formularios y analytics pueden vivir en el mismo repo. Nx no solo acelera: ayuda a explicar si una página con ingresos está afectada. Si cambia libs/cta, el grafo indica qué páginas revisar. Si cambia libs/analytics, affected CI indica qué apps necesitan smoke test.
Esto sirve para layouts de AdSense, bloques de afiliado, CTAs de checkout y formularios de consulta. Para estandarizar Claude Code y monorepos en equipo, visita ClaudeCodeLab training. Si trabajas solo, crea este workspace y guarda una captura de nx graph antes de añadir más packages.
Verificación práctica
En mi prueba como Masa, creé primero solo web, admin, api, ui y contracts. Al cambiar un tipo en libs/contracts, pnpm nx affected -t test build --base=main --head=HEAD seleccionó las apps que dependían de contracts. Al cambiar solo libs/ui, el build de la API quedó fuera. La lección no fue memorizar opciones de Nx, sino hacer visibles el grafo y los límites antes de pedir cambios a Claude Code.
Resumen
Nx Workspace no existe para hacer enorme tu repositorio. Sirve para ver dependencias, verificar solo proyectos afectados y darle a Claude Code límites claros.
Empieza pequeño, lee project.json, inspecciona nx graph y pon nx affected en CI. Con eso, Claude Code deja de ser un generador de archivos y se convierte en un revisor útil de la estructura del monorepo.
PDF gratis: cheatsheet de Claude Code
Introduce tu email y descarga una hoja con comandos, hábitos de revisión y flujos seguros.
Cuidamos tus datos y no enviamos spam.
Sobre el autor
Masa
Ingeniero enfocado en workflows prácticos con Claude Code.
Artículos relacionados
Workflow de Obsidian a CLAUDE.md con Claude Code
Convierte notas de trabajo de Obsidian en notas operativas de CLAUDE.md para no repetir contexto.
Claude Code Revenue CTA Routing: de artículos a PDF, Gumroad y consulta
Un flujo con Claude Code para dirigir lectores a PDF gratis, Gumroad o consulta según intención.
Reglas de handoff para equipos con Claude Code: evidencia, permisos, rollback e ingresos
Formato práctico para entregar trabajo de Claude Code con pruebas, permisos, rollback, PDF gratis, Gumroad y consulta.