Monorepositorio con TypeScript: organización del código y mejores prácticas

Introducción a los monorepositorios con TypeScript

Con el crecimiento de la complejidad de las aplicaciones web modernas, los desarrolladores se enfrentan cada vez más al problema de la gestión del código. Cuando un proyecto consta de múltiples módulos interconectados — frontend, backend, bibliotecas de uso general — el enfoque tradicional con repositorios separados (polyrepo) puede provocar duplicación de código, desincronización de versiones y dificultades en la refactorización.

Un monorepositorio (monorepo) es una estrategia en la que el código de varios proyectos se almacena en un solo repositorio. En combinación con TypeScript, el monorepositorio se convierte en una herramienta potente: el tipado estricto garantiza la seguridad de los cambios en toda la pila, y un sistema de compilación unificado simplifica la gestión de dependencias.

En este artículo, veremos cómo organizar un monorepositorio con TypeScript: desde la estructura básica hasta herramientas avanzadas como Nx y Turborepo.

Ventajas del monorepositorio para proyectos TypeScript

Antes de pasar a la práctica, analicemos por qué el monorepositorio es especialmente beneficioso para proyectos TypeScript:

• Tipado unificado — TypeScript permite reutilizar interfaces y tipos entre paquetes sin duplicación.
• Commits atómicos — los cambios en la API y sus consumidores se pueden realizar en un solo commit, lo que simplifica la revisión y la reversión.
• Refactorización simplificada — el IDE (por ejemplo, VS Code) maneja correctamente los cambios de nombre y movimiento de archivos en todo el repositorio.
• Almacenamiento en caché de compilaciones — herramientas como Nx almacenan en caché los resultados de la compilación, acelerando el CI/CD.

Estructura básica del monorepositorio

Empecemos con una estructura simple pero efectiva. Crearemos un proyecto raíz y varios paquetes:

my-monorepo/├── packages/│   ├── shared/          # Tipos y utilidades compartidas│   │   ├── src/│   │   ├── package.json│   │   └── tsconfig.json│   ├── server/          # Backend (por ejemplo, Express)│   │   ├── src/│   │   ├── package.json│   │   └── tsconfig.json│   └── web/             # Frontend (React)│       ├── src/│       ├── package.json│       └── tsconfig.json├── package.json         # package.json raíz├── tsconfig.base.json   # tsconfig base para todos los paquetes└── .gitignore

El package.json raíz debe contener la configuración de workspace. Para npm y Yarn se ve así:

{  "name": "my-monorepo",  "private": true,  "workspaces": [    "packages/*"  ],  "scripts": {    "build": "tsc --build",    "clean": "tsc --build --clean"  }}

El tsconfig.base.json base define la configuración de compilación común:

{  "compilerOptions": {    "target": "ES2020",    "module": "commonjs",    "strict": true,    "esModuleInterop": true,    "skipLibCheck": true,    "forceConsistentCasingInFileNames": true,    "declaration": true,    "declarationMap": true,    "sourceMap": true,    "composite": true  }}

Cada paquete extiende la configuración base:

{  "extends": "../../tsconfig.base.json",  "compilerOptions": {    "outDir": "./dist",    "rootDir": "./src"  },  "include": ["src"]}

Gestión de dependencias y TypeScript paths

Uno de los problemas clave de los monorepositorios es la configuración correcta de las importaciones entre paquetes. En lugar de publicar paquetes en npm, utilizamos TypeScript Project References y paths.

Configuración de Project References

Añadamos en el tsconfig.json raíz las referencias a los proyectos:

{  "files": [],  "references": [    { "path": "./packages/shared" },    { "path": "./packages/server" },    { "path": "./packages/web" }  ]}

Ahora, al ejecutar