Monorepo vs Polyrepo: Una arquitectura sin sorpresas

Monorepo vs polyrepo es un debate que reaparece cada vez que tu equipo de ingeniería crece más rápido que tus tiempos de compilación. La respuesta corta: un monorepo gana cuando los equipos comparten código regularmente y coordinan cambios en una superficie común; un polyrepo gana cuando los equipos son genuinamente independientes y desployan sin esperar nunca a los demás. Todo lo demás depende de qué tan acoplados estén realmente tus servicios y cuánto costo de coordinación estés dispuesto a asumir. Este artículo te lleva por los trade-offs reales, las señales que apuntan en una dirección u otra, y un marco práctico para tomar la decisión.

La pregunta correcta es sobre acoplamiento, no sobre cantidad de repos

La mayoría de los debates monorepo vs polyrepo comienzan con la pregunta equivocada. La cantidad de repos no es el problema. El problema es si tus equipos necesitan moverse juntos.

Si los cambios del Equipo A frecuentemente requieren que el Equipo B actualice algo en el mismo ciclo de lanzamiento, tienes trabajo fuertemente acoplado. Un repo para eso es casi siempre la respuesta más limpia. Si el Equipo A y el Equipo B lanzan en sus propias agendas, tocan partes diferentes del sistema y nunca se esperan mutuamente, los repos separados tienen sentido genuino.

El peor resultado posible: dos repos separados para código que aún necesita desplegarse junto. Obtienes todo el costo de coordinación de un monorepo sin ninguno de los beneficios. Tus equipos terminan abriendo PRs en repo A y repo B simultáneamente, esperando que ambos pasen CI al mismo tiempo. Este patrón es sorprendentemente común en organizaciones que eligieron polyrepo temprano y luego dejaron que sus servicios se volvieran más interdependientes de lo originalmente planeado.

El primer paso antes de elegir cualquier cosa es dibujar un mapa de dependencias simple. Lista cada servicio o paquete que tienes y dibuja flechas donde uno depende de otro. Si las flechas forman un cluster denso, ese cluster pertenece a un repo.

Por qué Google, Meta y Microsoft eligieron monorepos a gran escala

Google mantiene la mayoría de su código en un único repositorio estimado en más de 80 TB de datos y 2 mil millones de líneas de código. Meta y Microsoft hacen lo mismo para sus superficies de producto principales. Esto no es porque a las grandes empresas les encanta la complejidad, sino porque a escala, mantener las dependencias sincronizadas en cientos de repos se convierte en un problema de ingeniería a tiempo completo.

Un único cambio de API en una librería compartida podría requerir actualizaciones coordinadas en 40 repos diferentes. En un monorepo, eso es un único pull request. Una revisión. Un merge. Un rollback si algo sale mal.

Según investigaciones publicadas por Sourcegraph, el 63% de las empresas con 50 o más desarrolladores ahora utilizan un monorepo para al menos parte de su base de código, un aumento considerable respecto a hace tres años.

El beneficio concreto que más importa: commits atómicos. Cuando un cambio que rompe tu API también requiere actualizaciones de frontend y backend, un monorepo te permite aterrizar los tres cambios en un PR, probarlos juntos, y hacer rollback de los tres como una unidad si algo sale mal. Con polyrepo, abres tres PRs separados, esperas tres ciclos de revisión, y gestionas una ventana donde tus servicios ejecutan versiones desacopladas.

Un equipo de ingeniería reportó pasar de despliegues ocasionales a más de 40 lanzamientos de aplicaciones por semana después de migrar sus paquetes de frontend a un monorepo Nx. Las actualizaciones de Angular que anteriormente tomaban meses se convirtieron en tareas rutinarias que los equipos manejaban sin detener otro trabajo.

El costo oculto de coordinación en polyrepo

Polyrepo tiene ventajas reales que vale la pena tomar en serio. Cada equipo controla su propio pipeline de CI/CD, su propio cadencia de lanzamiento, sus propios controles de acceso. Los equipos de seguridad y cumplimiento frecuentemente lo prefieren: el acceso al código puede restringirse a personal designado por repo, lo que importa en industrias reguladas. Los componentes de código abierto viven más limpiamente en sus propios repos públicos sin exponer código interno.

Para equipos que son genuinamente independientes, estas ventajas son reales. Un pequeño equipo de servicios que posee un pipeline de datos ejecutándose en su propio calendario y sin tocar código compartido tiene poco que ganar sentándose dentro de un monorepo más grande.

Pero las organizaciones polyrepo acumulan silenciosamente costos que no aparecieron en la decisión original. El versionado de dependencias entre repos se convierte en su propia disciplina. Una librería de utilidad compartida envejece en algunos repos mientras se mantiene actualizada en otros. Alguien tiene que mantener una matriz de compatibilidad solo para saber qué versión de cuál librería funciona con qué versión de cuál servicio.

Una métrica que vale la pena conocer: el tiempo mediano de ciclo de PR en monorepos ronda las 19 horas, versus aproximadamente 2 horas en polyrepos. Los PRs en monorepos tienden a ser más grandes porque tocan más superficies, lo que ralentiza la revisión. Pero cuando un cambio de polyrepo requiere tres PRs coordinados entre tres repos para desplegar una única característica, el tiempo de ciclo agregado frecuentemente excede la cifra de monorepo de todas formas, con el riesgo añadido de merges parciales que dejan los servicios en estados inconsistentes.

El patrón que sorprende a los equipos: "comenzamos con repos separados por independencia, pero ahora cada lanzamiento requiere abrir PRs en cuatro lugares." En ese punto tienes lo peor de ambos mundos.

Los tiempos de compilación dejaron de ser el factor decisivo en 2024

La objeción clásica a los monorepos eran los tiempos de compilación. Si tu repo tiene 200 paquetes y cambias un archivo, ¿realmente quieres recompilar los 200?

Este argumento expiró en algún lugar alrededor de 2022 a 2024, dependiendo de tu stack.

Las herramientas modernas de compilación utilizan cachés conscientes del contenido. Solo recompilan lo que cambió, y saltan cualquier cosa con inputs idénticos. Un cambio en el paquete payments no dispara una recompilación de design-system si nada en design-system cambió. GitHub Actions proporciona 10 GB de almacenamiento de caché libre antes de que necesites una solución de caché remoto pagada.

Turborepo maneja bien la mayoría de equipos de JavaScript y TypeScript hasta alrededor de 20 paquetes. La configuración es un único turbo.json, el cachés remoto funciona en Vercel de forma gratuita o autohospedado, y la curva de aprendizaje es lo suficientemente baja para que un equipo sea productivo en un día.

Pasados 20 paquetes, o cuando la compilación abarca múltiples lenguajes, el enfoque más estructurado de Nx tiende a justificar la curva de aprendizaje más pronunciada. Nx agrega generación de código, distribución automática de CI, y seguimiento fino de dependencias que se vuelven cada vez más valiosos a medida que el repo crece.

Para organizaciones muy grandes ejecutando miles de paquetes en múltiples lenguajes, Bazel (el sistema de compilación de código abierto de Google) es la única herramienta diseñada para esa escala. El costo de configuración es significativo y casi siempre requiere un equipo dedicado de ingeniería de plataforma.

Cuatro preguntas que resuelven el debate para tu equipo

No hay una respuesta correcta universal, pero hay un marco confiable.

1. ¿Tus equipos comparten código que cambia frecuentemente? Si sí, un sistema de diseño compartido, una librería de cliente API compartida, lógica de autenticación compartida, un monorepo es casi siempre la mejor opción. Mantener una librería compartida sincronizada entre múltiples repos requiere disciplina constante y casi siempre se desincroniza.

2. ¿Tus equipos despliegan de forma independiente? Si el Equipo A lanza su servicio el martes y el Equipo B lanza el jueves sin coordinación necesaria, polyrepo gana su lugar. Si lanzar un servicio requiere el lanzamiento simultáneo de otro, ese costo de acoplamiento debe estar en la ecuación.

3. ¿Cuántos ingenieros están tocando esta base de código? Por debajo de 20 ingenieros, la estructura del repo importa menos de lo que crees. Por encima de 50, los costos de coordinación de polyrepo comienzan a acumularse visiblemente. Por encima de 200, el caso para un monorepo se vuelve muy fuerte a menos que los equipos estén genuinamente aislados por producto y tecnología.

4. ¿Tienes requisitos de seguridad o cumplimiento que aíslen el código por equipo? En industrias reguladas, finanzas, salud, algunos contextos gubernamentales, el acceso al código puede necesitar estar restringido a personal designado. Esa restricción puede anular las otras respuestas. Si el aislamiento de código duro es un requisito de cumplimiento, polyrepo no es una opción, es una restricción.

Si respondiste "sí" a la pregunta 1 y "no" a la pregunta 4, un monorepo es casi con certeza la llamada correcta. Si respondiste "no" a la pregunta 1 y "sí" a la pregunta 2, polyrepo es una opción defensible. Todo lo demás es una decisión que requiere criterio.

Lo que la mayoría de equipos en crecimiento realmente elige

Muy pocas organizaciones de ingeniería maduras operan en cualquiera de los extremos. El patrón que aparece más frecuentemente: un monorepo para el producto central (frontend, librerías compartidas, servicios de backend que dependen mutuamente), y repos separados para componentes genuinamente independientes.

Un pipeline de datos que ejecuta en su propio calendario y comparte cero código con el producto principal pertenece fuera del monorepo. Una herramienta interna mantenida por un equipo de una sola persona pertenece fuera. Una librería de código abierto que necesita visibilidad pública pertenece fuera.

Esto no es un compromiso. Es la respuesta correcta a una pregunta que raramente tiene una respuesta binaria limpia. Mantén juntas las cosas que necesitan moverse juntas. Separa lo que es genuinamente independiente.

Lo importante es tomar la decisión deliberadamente, no por defecto. La mayoría de equipos que terminan con dispersión polyrepo no la eligieron: comenzaron un servicio, luego otro, luego otro, y nunca se detuvieron a preguntarse si esos servicios necesitaban vivir juntos.

La herramienta que hace que cualquiera de los enfoques funcione realmente

Para monorepos:

• Nx: conjunto de características más fuerte, bueno para compilaciones políglotas y equipos más allá de 20 paquetes. Curva de aprendizaje más pronunciada pero escala más lejos.

• Turborepo: más simple para comenzar, excelente para equipos de JS/TS menores a 20 paquetes. Cachés nativos de Vercel u opciones autohospedadas.

• Bazel: para repos multi-lenguaje muy grandes a escala empresarial. Inversión de configuración significativa requerida.

Para polyrepos:

• Una disciplina de versionado para librerías compartidas no es opcional. Sin versionado semántico y un proceso de changelog consistente, la desincronización de dependencias se convierte en la norma dentro de seis meses.

• Herramientas de CI/CD que disparan pipelines entre repos cuando una dependencia compartida cambia. GitHub Actions lo soporta a través de eventos workflow_dispatch y repository_dispatch entre repos.

• Un registro de dependencias (npm private registry, GitHub Packages, Artifactory) para gestionar la distribución de paquetes compartidos.

Biscuit puede traer el archivo de configuración. La llamada sobre cuál usar sigue siendo un asunto de esas cuatro preguntas.