Project references: TypeScript a escala

Un proyecto crece, y a veces se parte en varios: una app, una librería compartida, un paquete de utilidades —todos en un mismo repositorio (un monorepo)—. Los project references de TypeScript orquestan esos proyectos: compilan solo lo que cambió, imponen límites claros entre ellos, y aceleran todo. Es la configuración a escala, la que usan los equipos grandes.

El edificio dividido en alas independientes

El problema: compilar todo, siempre

En un monorepo con varios paquetes, sin project references, tsc trata todo como una masa: cualquier cambio recompila el mundo entero, y no hay límites claros de quién puede importar de quién. Los project references dividen eso en unidades con dependencias declaradas:

// un monorepo típico:
//   packages/
//     ui/          (librería de componentes)
//     utils/       (utilidades compartidas)
//     app/         (la aplicación, usa ui y utils)

// cada paquete tiene su tsconfig con "composite": true, y el de la app
// DECLARA de quién depende con "references":

{
"compilerOptions": {
  "composite": true       // habilita que este proyecto sea referenciable
},
"references": [
  { "path": "../ui" },    // la app depende de ui
  { "path": "../utils" }  // y de utils
]
}

composite: true marca un proyecto como una unidad "referenciable" (TS genera información extra para compilarlo por separado). references declara sus dependencias. Con eso, tsc --build compila los proyectos en el ORDEN correcto (primero ui y utils, luego app) y, en las siguientes veces, solo recompila lo que cambió.

Qué te dan

¿Los necesitas?

Mini-reto

De reconocimiento, no de código: 1) busca un proyecto open source que sea un monorepo (muchos tienen una carpeta packages/) y mira si sus tsconfig.json usan composite y references; 2) dibuja en un papel el grafo de dependencias de tres paquetes ficticios (app → ui → utils) y escribe qué references tendría cada uno; 3) reflexiona: ¿tu proyecto actual los necesita? (casi seguro que no, y eso está bien). Reconocer la herramienta es el objetivo.

Qué sigue

Tu configuración de TypeScript está completa. Falta el compañero que trabaja a su lado: ESLint. La próxima lección conecta ESLint con TypeScript para un linting que ENTIENDE los tipos —cazando problemas que ni el compilador ni un linter normal ven por separado. La última pieza del entorno profesional.