Monorepositorio con TypeScript: organización de código en la práctica

Monorepositorio con TypeScript: organización del código en la práctica

El desarrollo moderno de frontend y backend se enfrenta cada vez más al problema de gestionar múltiples proyectos interrelacionados. Cuando la cantidad de paquetes, bibliotecas y aplicaciones crece, el enfoque tradicional con repositorios separados (multi-repo) comienza a ralentizar el desarrollo: duplicación de código, dificultades con la sincronización de versiones y ciclos de revisión largos. La solución es un monorepositorio (monorepo), especialmente en combinación con TypeScript. En este artículo, analizaremos los aspectos prácticos de la organización del código en un monorepositorio con TypeScript: desde la selección de herramientas hasta ejemplos concretos de estructura y configuración.

¿Qué es un monorepositorio y por qué es necesario para proyectos TypeScript?

Un monorepositorio es un enfoque en el que el código de varios proyectos (paquetes, bibliotecas, servicios) se almacena en un único repositorio Git. Para TypeScript esto es especialmente relevante, ya que el lenguaje de tipado estricto permite reutilizar fácilmente tipos e interfaces comunes entre diferentes partes del sistema.

Principales ventajas de un monorepositorio con TypeScript:

• Versión única de dependencias — se elimina la situación en la que diferentes proyectos usan distintas versiones de una misma biblioteca.
• Reutilización de código — tipos comunes, utilidades y configuraciones están fácilmente disponibles para todos los paquetes.
• Commits atómicos — los cambios que afectan a varios paquetes se pueden commitear juntos.
• Simplificación de CI/CD — un solo pipeline para compilar y probar todas las partes.

Sin embargo, un monorepositorio requiere disciplina en la organización del código. Sin una estructura adecuada, se convierte en un "vertedero". TypeScript ayuda a poner orden gracias al tipado estricto y al sistema modular.

Selección de la herramienta para gestionar el monorepositorio

En el mercado existen varias herramientas populares para trabajar con monorepositorios. Consideremos las dos más comunes para TypeScript: Nx y Turborepo.

Nx — un sistema potente con soporte para monorepositorios, generación de código y almacenamiento en caché avanzado. Es ideal para proyectos grandes con muchos paquetes.

Turborepo — una herramienta más ligera y rápida de Vercel, enfocada en la simplicidad. Es perfecta para proyectos medianos y equipos que desean una configuración mínima.

Ejemplo de configuración básica con Turborepo:

// turbo.json{  "$schema": "https://turbo.build/schema.json",  "pipeline": {    "build": {      "dependsOn": ["^build"],      "outputs": ["dist/**"]    },    "test": {      "dependsOn": ["build"]    },    "lint": {}  }}

Para TypeScript es obligatoria la configuración de tsconfig.json con soporte para project references. Esto permite que el compilador entienda las dependencias entre paquetes.

// tsconfig.base.json{  "compilerOptions": {    "target": "ES2020",    "module": "ESNext",    "moduleResolution": "bundler",    "strict": true,    "composite": true,    "declaration": true,    "declarationMap": true,    "sourceMap": true,    "outDir": "./dist",    "rootDir": "./src"  }}

Organización práctica de la estructura del monorepositorio

El principio clave es dividir el código en capas lógicas. Consideremos una estructura típica para un monorepositorio TypeScript con una aplicación web y un backend:

monorepo/├── apps/│   ├── web/          # Aplicación Frontend (React, Vue, etc.)│   └── api/          # Servicio Backend (Express, NestJS)├── packages/│   ├── shared/       # Tipos e interfaces comunes│   ├── utils/        # Funciones utilitarias│   ├── ui/           # Componentes UI (si se usan)│   └── config/       # Configuraciones comunes (eslint, tsconfig)├── tools/            # Scripts y herramientas para CI/CD├── turbo.json├── package.json└── tsconfig.