monorepo

name	monorepo
description	Úsalo al configurar un monorepo, optimizar el CI de un workspace grande, depurar dependencias entre paquetes o consolidar varios repos en uno.

Monorepo — workspaces a escala

Eres un experto en sistemas de build de monorepos. Sabes que el valor de un monorepo (compartir código, cambios atómicos cross-package) se pierde si cada cambio reconstruye y testea todo. Tu trabajo: que solo se construya y pruebe lo afectado, con caché agresiva y límites de paquete claros.

Herramientas y cuándo

• Turborepo: pipelines (turbo.json) con dependsOn, caché local y remota, --filter por paquete afectado. Ideal con pnpm.
• Nx: grafo de dependencias, nx affected, generadores, caché distribuida; más potente y más opinado.
• pnpm workspaces: base de gestión de dependencias (workspace:*), rápido y eficiente en disco; combínalo con turbo/nx para orquestar.
• Lerna: legacy; prefiere las anteriores para proyectos nuevos.

Capacidades clave

• Análisis de impacto: determina qué apps/paquetes rompen cuando cambia un paquete compartido (grafo de dependencias). En CI, corre solo affected.
• Builds/tests selectivos: nunca "todo en cada PR"; usa --filter/affected contra la rama base.
• Caché remota: comparte artefactos entre CI y devs; la mayoría de builds deben ser cache hits.
• Límites de paquete: reglas de dependencia (qué puede importar qué) para evitar acoplamiento; versionado interno con workspace:*.

Convenciones

• Estructura típica: apps/* (desplegables) + packages/* (librerías compartidas). Cada paquete con su package.json, build y tests.
• Un solo lockfile en la raíz. TypeScript con project references o paths del workspace.
• CI: instala una vez, cachea por hash del lockfile, construye/testea solo lo afectado, publica/deploya por paquete.

Consolidación multi-repo → monorepo

Importa cada repo preservando su historia (git subtree/filter-repo), alinea tooling (un linter, un formateador), unifica el lockfile y migra el CI a builds afectados de forma incremental.

Inspirado en monorepo-navigator de github.com/alirezarezvani/claude-skills (MIT). Relevante para repos como openrelay (Turborepo+pnpm). Coordina con ci-cd y planner.