Monorepo

  • Backend
  • nx
  • microservicios

    Conceptos clave

  • Un monorepo es una estrategia donde múltiples proyectos, paquetes o servicios viven dentro de un único repositorio central.
  • Permite compartir código, estandarizar tooling, mejorar DX (developer experience) y simplificar la gestión de dependencias.
  • Herramientas comunes: nx, npm workspaces, Turborepo, Bazel.
  • Facilita prácticas de CICD consistentes al centralizar pipelines.
  • Ventajas:
    • Reutilización de librerías internas.
    • Refactors atómicos y cambios transversales.
    • Menos overhead de sincronización entre repos.
    • Mayor coherencia en estándares, linters y tooling.
  • Desventajas:
    • Requiere herramientas para escala, caching, restricciones por proyecto.
    • Riesgo de builds más lentos si no se gestiona bien.
  • Usos comunes:
    • Equipos que construyen múltiples apps y librerías coordinadas.
    • Arquitecturas que combinan microservicios con partes compartidas (relacion entre monorepos y microservicios con ejemplos).

Herramientas principales

  • nx
    • Ayuda a organizar proyectos, generar apps/libs, aplicar boundary rules, caching distribuido, graph de dependencias.
    • Útil para controlar escalabilidad y automatizar procesos complejos.
    • Extensiones útiles: generators, executors, affected commands.
    • catching
  • npm workspaces
    • npm
    • Permiten agrupar múltiples paquetes en un mismo repositorio sin tooling externo.
    • Integración básica con scripts, dependencias compartidas y linking automático.
    • Recursos:
      • Cómo crear monorepositorios con Npm workspaces-
      • Using npm Workspaces with Docker-
      • workspaces npm Docs-workspaces
      • Mastering npm Workspaces A Comprehensive Guide for Beginners-mastering-
    • Ejemplo práctico:

Documentación y guías

  • monorepos guia basica
  • Igvirmonorepo-guidelines Desarrollo de aplicaciones con arquitectura mono-repositorio
  • Monorepos A Comprehensive Guide with Examples
  • gpt ejemplo basico de nx monorepo

Organización de un monorepo

  • Estructura típica:
    • /apps
      • Contiene aplicaciones productivas: frontends, backends, CLIs.
    • /libs
      • Librerías internas compartidas: UI, utils, domain, infraestructura.
    • /tools
      • Scripts, automatizaciones, generadores, CI helpers.
    • /configs
      • Configuraciones centralizadas: ESLint, Prettier, tsconfig, Dockerfiles base.
  • Buenas prácticas:
    • Establecer fronteras explícitas entre proyectos (domain boundaries).
    • Usar versionado interno coherente (semver o locked).
    • Mantener scripts globales que ejecuten tareas por paquete.
    • Controlar dependencias prohibidas mediante constraints.
    • Mantener tests aislados por paquete pero permitir tests cross-package cuando sea necesario.

Monorepos y CICD

  • Los pipelines pueden optimizarse mediante:
    • Caching por proyecto (nx cache remoto o caching manual).
    • Ejecución selectiva por cambios (affected en Nx).
    • Workflows centralizados que detectan qué apps deben desplegarse.
  • Modelo de pipeline:
    • Lint → Build → Test → Deploy por paquete afectado.
    • Reutilización de artefactos entre servicios.

Code Examples (npm workspaces + Docker)

Ejemplo básico de estructura npm workspaces

{
	"private": true,
	"workspaces": [
		"packages/*",
		"apps/*"
	]
}

`

Dockerfile minimal para workspaces

FROM node:20

WORKDIR /repo

COPY package.json package-lock.json ./
RUN npm install

COPY . .
RUN npm run build

Script de workspace con linking entre paquetes

{
	"scripts": {
		"build": "npm run build -ws",
		"test": "npm run test -ws",
		"dev": "npm run dev -w apps/api"
	}
}

Monorepo: Conceptos Avanzados y Temas Complementarios

Filosofías de diseño en monorepos

  • Integrated Monorepo
    • Enfoque donde todos los paquetes comparten dependencias, configs y tooling.
    • Propio de entornos Node con npm workspaces, Yarn Berry o nx.
    • Favorece DX y velocidad de desarrollo.
  • Isolated Monorepo
    • Cada paquete mantiene dependencias independientes y build aislado.
    • Usado en setups con microservicios heterogéneos (Go, Python, Node mezclados).
    • Requiere tooling más flexible (Bazel, Pants).
  • Hybrid Monorepo
    • Combinación donde las librerías internas están integradas, pero las apps/productos están parcialmente aislados.
    • Ideal para empresas con múltiples equipos autónomos.

Dependency Management avanzado

  • Hoisting
    • Mecanismo para colocar dependencias comunes en la raíz del repo.
    • Reduce tamaño de instalación, pero puede causar conflictos con resoluciones de versiones.
  • No-hoist / instalaciones por paquete
    • Aislamiento total útil cuando se requiere reproducibilidad estricta.
    • Más lento pero más seguro para entornos con servicios variados.
  • Constraints y Rules
    • Permiten evitar imports no autorizados (libs/ui no puede acceder a libs/db).
    • En monorepos grandes es crítico para evitar arquitectura enrevesada.
    • nx ofrece reglas formales mediante project.json y tsconfig.base.json.

Tipos de monorepos según arquitectura

  • Monorepo orientado a producto
    • Un solo producto con múltiples módulos compartidos.
    • Ejemplo: varias apps de una misma plataforma con librerías comunes.
  • Monorepo orientado a plataforma
    • Varios productos + librerías + dominio + infra centralizada.
    • Facilita la “plataforma interna” que comparten múltiples equipos.
  • Polyglot monorepo
    • Usa múltiples lenguajes: Java + Node + Python + Go.
    • Requiere herramientas de build multiplataforma (Bazel, Pants).
    • Retos: caching, runtime distinto, testing heterogéneo.

Estrategias de versionado dentro del monorepo

  • Versionado unificado (single version)
    • Un número de versión para todo el repo.
    • Simple pero rígido.
  • Versionado independiente por paquete
    • Cada proyecto tiene su propio semver.
    • Ideal cuando cada servicio o librería tiene su ciclo independiente.
  • Release groups / release channels
    • Subconjuntos de paquetes versionados en conjunto (ej: “backend core”, “frontend libs”).
    • Útil en repos muy grandes o con equipos independientes.

Estrategias de branching adaptadas a monorepos

  • Trunk-based development
    • Lo más común y eficiente para monorepos.
    • Requiere CI rápido y buena automatización.
  • Short-lived feature branches
    • Las ramas deben ser muy cortas para evitar conflictos frecuentes.
    • Imprescindible usar pre-merge checks por paquete.
  • Release branches por app o servicio
    • Cuando hay múltiples productos dentro del monorepo con ciclos distintos.

Infraestructura y automatización específica de monorepos

  • Task Runners distribuidos
    • Ejecución paralela y distribuida en CI.
    • nx lo maneja con computation cache remoto; otros usan Turborepo o Bazel.
  • Pipelines modulares
    • CI detecta qué apps deben ejecutarse (affected).
    • Evita pipelines globales lentos.
  • Bot interno de mantenimiento
    • Automatiza actualización de dependencias internas.
    • Detecta rompimientos entre proyectos y envía PRs automáticas.

Testing en monorepos

  • Unit tests por paquete
    • Cada proyecto tiene su propio scope.
  • Cross-package Integration Tests
    • Pruebas entre múltiples librerías o servicios.
  • Contract Testing
    • Especialmente útil cuando el monorepo incluye microservicios.
    • Ancla estabilidad entre módulos aunque vivan juntos.
  • Snapshot de APIs internas
    • Permite detectar breaking changes entre librerías internas.

Mantenimiento y gobernanza del monorepo

  • Codeowners por carpetas
    • Permite controlar qué equipo gestiona cada parte del repo.
    • Crítico en monorepos grandes para evitar caos.
  • Convenciones estrictas de naming y estructura
    • /apps, /libs, /domain, /infra, /configs, etc.
    • Previene deuda técnica y confusión a largo plazo.
  • Documentación interna generada automáticamente
    • Documentar dependencias entre proyectos.
    • Generación automática con herramientas de graphing.

Escalabilidad y performance

  • Caching distribuido
    • Reduce builds y tests hasta 70–90%.
    • Fundamental en monorepos grandes.
  • Computation memoization
    • Evita repetir tareas con mismos inputs/outputs.
    • nx es líder en esto.
  • Partial checkout / sparse checkout
    • Descarga solo partes del repo necesarias (importante si pesa varios GB).

Monorepo vs Multirepo: decisiones estratégicas

  • Monorepo es mejor cuando:
    • Hay alto nivel de código compartido.
    • Equipos trabajan sobre un producto o plataforma unificada.
    • Necesitas estándares globales.
  • Multirepo es mejor cuando:
    • Los servicios son totalmente autónomos.
    • Equipos no comparten tooling.
    • Hay entornos regulados que exigen despliegue aislado.

Casos de uso reales (resumen conceptual)

  • Google: monorepo masivo con tooling propietario.
  • Facebook/Meta: monorepo distribuido con Buck (similar a Bazel).
  • Airbnb / Uber: monorepos híbridos para frontend + libs internas.
  • Microsoft: varios monorepos grandes, incluido parte de VSCode.

Riesgos comunes a evitar

  • Crecimiento anárquico de librerías internas.
  • Import loops entre apps/libs.
  • Builds globales lentos por falta de caching.
  • Dependencias transversales no autorizadas.
  • Tooling insuficiente (por ejemplo, usar solo npm workspaces en repos demasiado grandes).

Checklist de calidad de un monorepo bien hecho

  • Hay reglas de boundaries claras.
  • Estructura fija y documentada.
  • Liberación y versionado bien definidos.
  • CI basado en afectación, no global.
  • Caching remoto activo.
  • Testing dividido por paquetes y testing cross-package.
  • Documentación interna actualizada.
  • Scripts y tooling centralizados.
  • Compatibilidad con Docker, Kubernetes o infraestructura de despliegue del equipo.

Monorepo: Panorama 2025 y Recursos Actualizados

Evolución reciente / Estado del arte 2025

Herramientas modernas y soporte actualizado

Buenas prácticas y recomendaciones 2025

Estudios recientes / riesgos emergentes

  • El estudio Pinning Is Futile: You Need More Than Local Dependency Versioning to Defend against Supply Chain Attacks (2025) demuestra que fijar versiones no basta para proteger monorepos del ataque a la cadena de suministro; se requieren estrategias colectivas y controles adicionales. arXiv link
  • En monorepos grandes y con TypeScript, optimizar builds y manejo de dependencias es esencial; el artículo Accelerating Large TypeScript Monorepo Builds and Dependency Management (2025) detalla estrategias modernas para ello. Leapcell blog

Guías, artículos y tutoriales recientes (2024–2025)

  • Complete Monorepo Guide: pnpm + Workspace + Changesets (2025) — guía práctica, con estructura, scripts, versionado y CI/CD. jsdev.space
  • Building a Better Monorepo with TypeScript, Turborepo or Nx (2024) — explicación paso a paso de cómo crear monorepos con TypeScript usando Turborepo o Nx. canopas.com
  • Tutorial oficial Building and Testing TypeScript Packages in Nx — un ejemplo práctico de configuración y uso de Nx con monorepos TS. nx.dev/docs

Tendencias 2025 y dirección en futuro cercano

Consideraciones al planificar un monorepo en 2025

  • Evalúa escala y lenguajes: para repos grandes → Nx + workspaces + project references.
  • Gestiona dependencias con pnpm y boundary rules; evita dependencias innecesarias.
  • Automatiza CI/CD con caching remoto y builds afectados.
  • Documenta estructura, ownership y reglas de arquitectura.
  • Audita dependencias externas (especialmente en npm).

Recursos recomendados 2025

Recurso / Artículo Qué aporta
A new Nx Experience For TypeScript Monorepos (2025) Buenas prácticas modernas para TS + Nx + workspaces + project references
Complete Monorepo Guide – pnpm + Workspaces + Changesets (2025) Configuración práctica y moderna para monorepos JS/TS
Crea un Monorepo con pnpm Workspaces (guía incluida en el artículo anterior) Tutorial accesible para iniciar un monorepo minimalista
Nx 22 Release (2025) Novedades en Nx: CI, caching distribuido, soporte ampliado y mejoras de plataforma
Accelerating Large TypeScript Monorepo Builds and Dependency Management (2025) Estrategias para optimizar builds y dependencias en monorepos TS grandes
Turborepo vs Nx / Monorepo con TypeScript (2024) Comparativa práctica de herramientas de monorepo según necesidades
Pinning Is Futile (2025) Análisis de seguridad y riesgos del version pinning en ecosistemas npm