Monorepos: Año de revisión

Un repositorio para gobernarlos a todos

Hace un año iniciamos la migración de nuestra suite de aplicaciones web a un monorepo y ha llegado el momento de compartir aprendizajes, aciertos y cómo lo hicimos posible. La meta era clara: simplificar la gestión de dependencias, reducir la duplicación de código y facilitar la expansión con nuevas apps y bibliotecas de funcionalidades reutilizables.

Éramos un equipo de desarrollo de dos personas, lo que nos obligó a que cada decisión contara: desde el alcance de la migración hasta el orden de traslado de las apps y el diseño de librerías compartidas. La ventaja de un equipo pequeño es evidente: decisiones rápidas, alta visibilidad de cambios y libertad para experimentar sin bloquear a demasiados implicados.

Nuestro enfoque

No podíamos pausar el desarrollo de nuevas funcionalidades ni la corrección de bugs en producción. Por eso optamos por una estrategia incremental: migrar una aplicación completa a la vez con todos sus módulos, empezando por una app pequeña para preparar el workspace, pipelines y tooling antes de escalar. Añadimos una regla práctica: la app en migración no recibiría nuevas features durante ese periodo; parches y fixes menores sí, evitando duplicar esfuerzos o generar confusión.

La tecnología: Nx y Nx Cloud

Elegimos Nx y Nx Cloud por su CLI bien documentada, ejemplos claros y plugins para nuestro stack. Esto nos dio confianza para aprender y validar sin frenar el avance ni sembrar dudas sobre el monorepo. Además, Nx Cloud nos permitió experimentar con caché y ejecución distribuida desde el inicio gracias a su plan gratuito.

Historias del camino

El formato de fechas nos jugó una pasada cuando dayjs y KendoReact no hablaban el mismo idioma. Dayjs usa formatos ISO como YYYY, mientras que KendoReact espera yyyy. La solución fue separar responsabilidades: usar dayjs para cálculos y comparaciones, y dejar todo el formateo visual a KendoReact, asegurando consistencia.

El wrapper de Keycloak para React que usábamos estaba desactualizado. Sin alternativas fiables, construimos el nuestro. Aprendimos a fondo los flujos de tokens, refresco y la integración con React. Resultado: un wrapper sólido y un equipo que comprende realmente la autenticación.

Una refactorización bienintencionada de componentes UI compartidos terminó tocando más de 150 archivos. Demasiado grande para revisar con seguridad. Lo revertimos y dividimos el trabajo en PRs pequeñas y enfocadas. Lección clave: los cambios masivos parecen eficientes, pero la iteración controlada gana en seguridad y previsibilidad.

La documentación que no sabíamos que necesitábamos llegó cuando invitamos a un equipo externo a revisar el workspace. Documentar decisiones, convenciones y estructuras nos obligó a pensar mejor, destapar huecos y hacer que la incorporación de nuevas personas fuera viable. Escribir no fue un trámite: se convirtió en una herramienta para razonar.

Qué código no migrar

No todo merece moverse al monorepo. Pregúntate si aporta valor, se usa a menudo y está bajo tu control. Si no cumple, quizá mejor dejarlo fuera. Sistemas de fin de vida, pruebas de concepto y prototipos rara vez compensan el esfuerzo. Herramientas de bajo impacto como dashboards internos pueden esperar. Módulos hiperestables o sensibles al rendimiento no se priorizan por uniformidad. Proyectos archivados o por cumplimiento legal no necesitan migrarse.

Efectos colaterales que nos encantaron

Actualizaciones sin drama de versiones: incluso antes de migrar todas las apps, ya ejecutábamos actualizaciones de todo el workspace entre migraciones. Con nx migrate, Nx actualizó dependencias de forma guiada y coherente.

Mejor experiencia de desarrollo: librerías compartidas, una única fuente de verdad y utilidades centralizadas simplificaron el trabajo local, el onboarding y la trazabilidad de componentes.

Reviews con foco: los módulos comunes están bien testeados, así que los PRs se concentran en la lógica de negocio y no en revisar patrones repetidos, un salto enorme frente al modelo de múltiples repos.

Confianza del equipo: al inicio no teníamos políticas estrictas de protección de la rama principal por limitaciones de configuración. Aun así, practicamos revisiones por responsabilidad compartida. No es lo ideal, pero funcionó para un equipo pequeño y alineado.

Lecciones aprendidas

Empezar con cabeza: montamos workspaces y pipelines de prueba para ganar confianza y reducir sorpresas. Definimos límites claros de qué migrar y qué quedaba fuera. Con generadores de Nx como workspace move pudimos ajustar la estructura más tarde sin bloquear el avance.

Avanzar por pasos: migrar app por app nos permitió validar, afinar tooling y aprender sin asumir riesgos excesivos. Aceptamos que las primeras soluciones no cubrirían todos los bordes y planificamos refactorizaciones incrementales.

Pragmatismo ante todo: evitar la sobreingeniería, apoyarnos en defaults y asumir duplicaciones temporales cuando aceleraban la entrega. Las abstracciones correctas llegan cuando conoces todos los casos de uso.

Documentar mientras trabajas: anotar decisiones, componentes y utilidades aclaró el pensamiento, aceleró el onboarding y convirtió la migración en un proceso más mantenible.

Limpiar de forma continua: dependencias obsoletas, scripts olvidados y rarezas afloran. Abordarlas pronto previene problemas mayores y mejora la calidad global.

Construir confianza con tests: pruebas rigurosas en módulos compartidos ahorran tiempo, reducen el riesgo al refactorizar y refuerzan la seguridad del equipo para evolucionar.

Conclusión

Tras un año, el monorepo no solo mejoró lo técnico: transformó la forma de trabajar. Cada migración exigió planificar, replantear abstracciones e iterar ante nuevos requisitos y casos límite. Hoy nuestras apps son más consistentes, las actualizaciones son más simples y crear nuevas aplicaciones es más rápido gracias a layouts, utilidades y flujos compartidos. Aún hay margen para pulir CI CD y onboarding, y nuestras librerías seguirán evolucionando, pero la base es sólida y el desarrollo diario es más predecible y menos propenso a errores.

En Q2BSTUDIO ayudamos a equipos y empresas a diseñar y escalar monorepos, creando aplicaciones a medida y software a medida con foco en calidad, seguridad y velocidad. Combinamos inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio y power bi, además de agentes IA e ia para empresas, para impulsar la entrega continua y la automatización. Si quieres acelerar tu plataforma con un monorepo, consulta nuestras aplicaciones a medida o potencia tu cadena de valor con automatización de procesos.

Un repo, muchas lecciones y posibilidades sin límite.