El problema que resuelven los catalogs

En un monorepo con treinta paquetes, react no aparece una vez: aparece treinta. Basta con que tres de esas declaraciones digan ^18.2.0, ^18.3.0 y ~18.2.1 para que tu grafo termine instalando dos copias de React que se ignoran entre sí. El problema no es estético: la versión de una dependencia es estado compartido disperso por decenas de archivos que nadie edita a la vez, y el estado compartido sin dueño siempre deriva. Los catalogs de pnpm existen para convertir ese estado disperso en una única fuente de verdad.

La deriva de versiones

Un workspace de pnpm da a cada paquete su propio package.json, y con él la libertad de declarar sus propias dependencias. Esa autonomía es deseable hasta que se vuelve fragmentación. Cuando escribes pnpm add zod en app-web el lunes y en ui-kit el jueves, pnpm fija en cada uno el último rango disponible en ese momento, y esos momentos no coinciden. Nadie decidió tener dos rangos de zod: emergieron de la asincronía de veinte personas trabajando en paralelo. A esto se le llama deriva de versiones —version drift o dependency skew—: la divergencia silenciosa de una misma dependencia declarada en muchos sitios sin un dueño que la unifique.

// apps/web/package.json
{ "dependencies": { "react": "^18.2.0" } }

// apps/admin/package.json
{ "dependencies": { "react": "^18.3.0" } }

// packages/ui-kit/package.json
{ "dependencies": { "react": "~18.2.1" } }

Nadie escribió esto de una sentada; se acumuló commit a commit. Y como cada rango se resolvió en un instante distinto, el grafo de instalación no tiene por qué converger en una sola versión.

flowchart TD
A[app-web quiere react 18.2.0] --> S[grafo de instalacion]
B[app-admin quiere react 18.3.0] --> S
C[ui-kit quiere react 18.2.1] --> S
S --> D[dos copias de react en node_modules]
style D fill:#eba0ac,color:#11111b

El grafo no miente: si los rangos no solapan en una única versión, pnpm resuelve más de una, y las instala. Lo que en un solo paquete sería imposible —dos versiones de React a la vez— en un monorepo es el estado hacia el que se tiende sin disciplina. Y hay una ironía: el node_modules estricto de pnpm, que no aplana ni miente sobre el árbol como hacía el hoisting de npm, es más honesto y por eso expone la doble copia en vez de ocultarla. La deriva siempre estuvo ahí; pnpm solo deja de disimularla.

Duplicar una dependencia es un bug, no solo peso

El instinto dice que dos copias de una librería solo cuestan disco y bytes de bundle. Para muchas dependencias es cierto; para las que mantienen estado global o identidad, es un fallo de correctitud. React es el ejemplo canónico: dos copias tienen dos registros internos de hooks distintos, y un componente renderizado por una copia y consumido por otra rompe con el célebre Invalid hook call. Lo mismo ocurre con la identidad de un Context: el createContext de la copia A no es el de la copia B, así que un Provider de una no alimenta al useContext de la otra, y el valor llega vacío sin ningún error de tipos que lo delate.

El patrón se repite en toda dependencia que asume ser un singleton: un cliente de estado cuyo store se duplica, una instancia de zod cuyos instanceof dejan de casar, una librería de estilos con su registro global de clases. El bug es especialmente cruel porque el checker de tipos no ve nada: cada paquete importó “la” librería y su tipo es correcto; solo en runtime, con dos copias físicas cargadas, la invariante de unicidad se viola. Depurarlo es un infierno precisamente porque el síntoma —un hook que falla, un contexto vacío— aparece lejísimos de la causa —dos rangos que no solapaban en un package.json que nadie miró—.

# la evidencia forense: el grafo confiesa dos versiones
pnpm why react
# react 18.2.0  <- de apps/web
# react 18.3.0  <- de apps/admin

Y aunque la librería no sea un singleton y no rompa nada, la doble copia sigue costando: el bundler no puede deduplicar lo que resuelve a versiones distintas, así que el usuario final descarga y ejecuta el mismo código dos veces. La deriva que en el peor caso es un bug, en el mejor caso es peso muerto que paga tu usuario.

Cómo se ve en el node_modules

Conviene aterrizar la abstracción en algo palpable. Con dos rangos incompatibles de React, el store de pnpm materializa dos versiones y el grafo enlaza a cada paquete con la suya. No es una advertencia teórica: es un directorio que puedes inspeccionar hoy mismo en tu repo.

pnpm ls react --depth -1 -r     # lista react en cada paquete del workspace
# apps/web      react 18.2.0
# apps/admin    react 18.3.0
# packages/ui   react 18.2.1    <- tres versiones, tres realidades

Cada una de esas líneas es un paquete que, en runtime, hablará con un React distinto. Si apps/web importa un componente de packages/ui, cruzan la frontera entre dos copias, y es exactamente ahí donde nace el Invalid hook call que después pasarás una tarde persiguiendo con un depurador, buscando en el código de tu componente un bug que en realidad vive en tres líneas de tres package.json que nadie miró juntas.

El coste humano: upgrades y conflictos de merge

Aun cuando los rangos solapan y no hay bug de runtime, la dispersión cobra un impuesto en tiempo humano. Subir React de ^18.2.0 a ^18.3.1 significa abrir treinta package.json, editar treinta líneas y confiar en no olvidar ninguna —porque la que olvides reintroduce la deriva—. Cada uno de esos cambios toca un archivo que otra rama probablemente también tocó, y el resultado es una cosecha de conflictos de merge en package.json que no aportan información: nadie discrepa sobre qué versión de React quiere, simplemente el archivo se ha vuelto un punto de contención mecánico.

# el tamano del problema, medido:
grep -rl '"react"' --include=package.json . | wc -l   # cuantos archivos hay que tocar
# basta olvidar uno para reabrir la deriva que creias cerrada

El impuesto se agrava con la automatización mal calibrada. Un bot como Renovate o Dependabot, al ver la misma dependencia en treinta manifiestos, puede abrir treinta pull requests —o uno gigantesco— para un solo upgrade conceptual. La señal (“hay una versión nueva de React”) es una; el ruido (“edita estos treinta sitios”) se multiplica por la dispersión. Centralizar la versión colapsa ese ruido a su tamaño real: un cambio, un sitio, un PR.

Y hay un coste de segundo orden, más sutil: el ruido erosiona la atención. Cuando cada upgrade trivial produce un diff de treinta archivos, los revisores dejan de leerlos de verdad y aprueban en automático, y esa fatiga es justo la grieta por la que se cuela el cambio de versión que sí importaba. La dispersión no solo cuesta tiempo directo; degrada la calidad de la revisión de todo lo demás que viaja en el mismo pull request.

Antes de los catalogs: detectar en vez de prevenir

La deriva no es un problema nuevo, y el ecosistema llevaba años parcheándolo por fuera. Herramientas como syncpack recorren todos los package.json y listan los rangos que no casan, ofreciendo alinearlos; convenciones de equipo piden “consulta la wiki antes de añadir una dependencia”. Funcionan, pero comparten una debilidad estructural: atacan el síntoma después de que aparezca. Corrigen la divergencia una vez ocurrida, dependen de correr en CI, y no impiden que se reintroduzca al minuto siguiente con el próximo pnpm add despistado.

# el enfoque clasico: detectar la divergencia a posteriori
pnpm dlx syncpack list-mismatches

Es la diferencia entre un detector de humos y un material ignífugo. El detector te avisa cuando ya hay fuego; el material hace que no pueda arder. Los catalogs aspiran a lo segundo: no a señalar la deriva, sino a eliminar la posibilidad de que exista.

flowchart TD
SIN[sin catalog tres rangos dispersos] --> DRIFT[deriva posible en cualquier commit]
CON[con catalog una entrada referenciada] --> ONE[una sola version garantizada]
style DRIFT fill:#eba0ac,color:#11111b
style ONE fill:#a6e3a1,color:#11111b

El salto conceptual es de gobernanza, no de herramienta: pasas de un mundo donde N archivos declaran versiones que pueden discrepar a uno donde una entrada declara la versión que todos heredan. La coherencia deja de ser un resultado que hay que lograr y vigilar, y pasa a ser la única forma que el sistema permite.