El protocolo catalog: resolución y reescritura al publicar

catalog: no es una versión: es un puntero a una versión. Y como todo puntero, hay dos preguntas que gobiernan su comportamiento: cómo se desreferencia cuando instalas dentro del monorepo, y qué pasa con él cuando el paquete cruza la frontera del repo al publicarse en npm, donde nadie tiene tu catálogo para resolverlo. La respuesta a la segunda —pnpm lo reescribe a un rango concreto al publicar— es lo que hace que los catalogs sean seguros para librerías que publicas, y no solo para apps internas. Entender esta indirección es entender por qué el protocolo es una comodidad interna que jamás se filtra al artefacto final.

Un protocolo es una forma de especificar, no una versión

En el campo de una dependencia, pnpm admite varias formas de especificar de dónde sale ese paquete: un rango de semver (^18.3.1), una ruta de archivo (file:../x), un enlace de workspace (workspace:*) o una entrada de catálogo (catalog:). Todas ocupan el mismo hueco sintáctico, pero solo el rango de semver es una versión de verdad; los demás son protocolos: instrucciones que le dicen a pnpm dónde ir a buscar la versión real. catalog: es una de esas instrucciones, y significa “ve al catálogo del workspace y usa lo que allí esté declarado para este paquete”.

La potencia de la idea está en que todos estos protocolos comparten el mismo hueco —el campo de versión— y por tanto son intercambiables sin cambiar la forma del package.json. Puedes empezar con ^18.3.1, pasar a catalog: cuando centralices, y en ambos casos el campo sigue siendo un campo de versión bien formado. El protocolo no es una sintaxis paralela ni un formato ajeno: es una extensión del mismo lugar donde siempre vivió la versión, y esa continuidad es la razón de que se integre sin fricción con todo el resto del ecosistema.

Merece nombrar los protocolos que comparten ese hueco, porque forman un vocabulario coherente: catalog: apunta al catálogo del workspace, workspace: a un paquete hermano del monorepo, file: o link: a una ruta del disco, y un rango de semver al registro público. Todos responden a la misma pregunta —de dónde sale esta dependencia— con orígenes distintos, y todos, salvo el rango de semver, son internos al repo.

Cómo se resuelve catalog: en la instalación

Cuando corres pnpm install, el protocolo se desreferencia en dos saltos. Primero, catalog: se expande al rango declarado en el catálogo —por ejemplo ^18.3.1—. Después, ese rango se resuelve, como cualquier otro, a la versión exacta disponible en el registro —por ejemplo 18.3.1—, y esa versión concreta es la que queda anclada en pnpm-lock.yaml.

catalogs:
  default:
    react:
      specifier: ^18.3.1
      version: 18.3.1
importers:
  apps/web:
    dependencies:
      react:
        specifier: 'catalog:'
        version: 18.3.1

Fíjate en el detalle revelador: el lockfile guarda una sección catalogs que fotografía el rango del catálogo y la versión a la que se resolvió, y en cada importer registra que el specifier era catalog: pero la version efectiva es 18.3.1. El puntero y su destino quedan ambos anotados. Por eso el lockfile sigue siendo la fuente de reproducibilidad: aunque el package.json diga solo catalog:, el lockfile sabe exactamente qué versión se instaló.

flowchart LR
A[package.json dice catalog] --> B[pnpm expande al rango del catalogo]
B --> C[resuelve el rango a version exacta]
C --> D[lockfile ancla la version concreta]
style A fill:#89b4fa,color:#11111b
style D fill:#a6e3a1,color:#11111b

Esta separación entre lo que declara el package.json y lo que ancla el lockfile es la que preserva la reproducibilidad tras adoptar catalogs. Un pnpm install --frozen-lockfile en CI no consulta el catálogo para decidir versiones: instala exactamente lo que el lockfile ya fijó, y usa la sección catalogs del lockfile solo para verificar que el catálogo del pnpm-workspace.yaml no ha cambiado por debajo. Si alguien edita el catálogo y no regenera el lockfile, la instalación frozen falla —que es justo lo que quieres—: el lockfile y el catálogo deben contar siempre la misma historia, y la que no cuadra se detecta antes de desplegar.

La reescritura al publicar

Aquí está la pieza que hace todo el sistema viable para librerías. El protocolo catalog: solo tiene sentido dentro del workspace que define el catálogo. Un consumidor externo que instale tu paquete desde npm no tiene tu pnpm-workspace.yaml y no sabría qué significa catalog:. Por eso pnpm lo elimina al empaquetar: tanto pnpm publish como pnpm pack reescriben cada catalog: al rango concreto que tenía en el catálogo en ese momento.

{
  "name": "@acme/ui",
  "dependencies": {
    "react": "catalog:react18"
  }
}

{
  "name": "@acme/ui",
  "dependencies": {
    "react": "^18.3.1"
  }
}

El artefacto que llega a npm es autocontenido: no contiene rastro del protocolo catalog:, sino el rango ^18.3.1 que cualquier package manager entiende. Tu comodidad interna —escribir catalog: y no repetir números— no se filtra al mundo exterior, que recibe un package.json perfectamente normal. Es una transformación de tiempo de publicación, análoga a compilar: el fuente usa una abstracción, el artefacto entregado ya no la necesita.

Repara en qué exactamente se escribe: el rango del catálogo, no la versión exacta que instalaste. Si el catálogo dice ^18.3.1, eso es lo que ve tu consumidor, conservando la flexibilidad de semver que tú elegiste al definir el rango. El catálogo no endurece de más las dependencias de tu paquete publicado; simplemente traslada al artefacto el mismo rango que habrías escrito a mano, pero garantizado idéntico al que usa el resto de tu repo.

# comprobarlo tu mismo, sin publicar nada:
pnpm pack                       # genera el tarball .tgz
tar -xzf acme-ui-1.0.0.tgz      # lo extraes
cat package/package.json        # y veras el rango concreto, no catalog:

Simetría con workspace: y por qué ninguno te ata

Si esta mecánica te suena, es porque ya la viste con workspace:. Cuando una librería interna depende de otra con workspace:*, pnpm reescribe ese marcador a la versión real del paquete hermano al publicar. catalog: sigue exactamente el mismo patrón, y no es casualidad: ambos son protocolos que solo existen dentro del workspace y ambos se borran en la frontera de publicación, sustituyéndose por lo que un consumidor externo puede entender.

// en el repo
{ "dependencies": { "react": "catalog:", "@acme/core": "workspace:*" } }

// publicado
{ "dependencies": { "react": "^18.3.1", "@acme/core": "1.4.2" } }

De aquí sale la consecuencia estratégica más importante: adoptar catalogs no ata a quien te consume. Como el marcador desaparece al publicar, el paquete que llega a npm no menciona catalogs en ninguna parte, y quien lo instale con npm, yarn o bun recibe rangos de semver ordinarios sin enterarse de que tú usaste un catálogo para producirlo. El coste de adopción recae enteramente en ti, el mantenedor; el beneficio de interoperabilidad se conserva intacto para el consumidor. Puedes catalogar una librería pública sin miedo a fragmentar a su comunidad ni a encadenarla a pnpm.

Esta propiedad convierte a los catalogs en una de esas raras mejoras que puedes adoptar de forma unilateral. No necesitas coordinar con tus consumidores, ni publicar una versión mayor, ni documentar una migración para quien te usa: el cambio es puramente interno a tu repo, y el mundo exterior recibe exactamente lo que recibía antes. Pocas decisiones de arquitectura son a la vez tan beneficiosas para el mantenedor y tan intrascendentes para el consumidor, y esa asimetría es la mejor señal de que la abstracción está trazada en el sitio correcto.