Los catálogos en Bun proporcionan una manera sencilla de compartir versiones de dependencias comunes entre múltiples paquetes en un monorepo. En lugar de especificar las mismas versiones repetidamente en cada paquete del espacio de trabajo, las defines una vez en el package.json raíz y las referencias consistentemente en todo tu proyecto.

Descripción general

A diferencia de la gestión tradicional de dependencias donde cada paquete del espacio de trabajo necesita especificar versiones independientemente, los catálogos te permiten:

1. Definir catálogos de versiones en el package.json raíz
2. Referenciar estas versiones con un simple protocolo catalog:
3. Actualizar todos los paquetes simultáneamente cambiando la versión en un solo lugar

Esto es especialmente útil en monorepos grandes donde docenas de paquetes necesitan usar la misma versión de dependencias clave.

Cómo usar los catálogos

Ejemplo de estructura de directorio

Considera un monorepo con la siguiente estructura:

my-monorepo/
├── package.json
├── bun.lock
└── packages/
    ├── app/
    │   └── package.json
    ├── ui/
    │   └── package.json
    └── utils/
        └── package.json

1. Definir catálogos en el package.json raíz

En tu package.json de nivel raíz, agrega un campo catalog o catalogs dentro del objeto workspaces:

{
  "name": "my-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0"
    },
    "catalogs": {
      "testing": {
        "jest": "30.0.0",
        "testing-library": "14.0.0"
      }
    }
  }
}

Si colocas catalog o catalogs en el nivel superior del archivo package.json, también funcionará.

2. Referenciar versiones del catálogo en paquetes del espacio de trabajo

En tus paquetes del espacio de trabajo, usa el protocolo catalog: para referenciar versiones:

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "jest": "catalog:testing"
  }
}

{
  "name": "ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "testing-library": "catalog:testing"
  }
}

3. Ejecutar Bun Install

Ejecuta bun install para instalar todas las dependencias según las versiones del catálogo.

Catalog vs Catalogs

Bun soporta dos formas de definir catálogos:

1. catalog (singular): Un catálogo predeterminado único para dependencias comúnmente usadas

   "catalog": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   }

   Referencia simplemente con catalog::

   "dependencies": {
     "react": "catalog:"
   }

2. catalogs (plural): Múltiples catálogos con nombre para agrupar dependencias

   "catalogs": {
     "testing": {
       "jest": "30.0.0"
     },
     "ui": {
       "tailwind": "4.0.0"
     }
   }

   Referencia con catalog:<name>:

   "dependencies": {
     "jest": "catalog:testing",
     "tailwind": "catalog:ui"
   }

Beneficios de usar catálogos

• Consistencia: Asegura que todos los paquetes usen la misma versión de dependencias críticas
• Mantenimiento: Actualiza una versión de dependencia en un solo lugar en lugar de en múltiples archivos package.json
• Claridad: Hace obvio qué dependencias están estandarizadas en todo tu monorepo
• Simplicidad: No hay necesidad de estrategias complejas de resolución de versiones o herramientas externas

Ejemplo del mundo real

Aquí hay un ejemplo más completo para una aplicación React:

package.json raíz

{
  "name": "react-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0",
      "react-router-dom": "^6.15.0"
    },
    "catalogs": {
      "build": {
        "webpack": "5.88.2",
        "babel": "7.22.10"
      },
      "testing": {
        "jest": "29.6.2",
        "react-testing-library": "14.0.0"
      }
    }
  },
  "devDependencies": {
    "typescript": "5.1.6"
  }
}

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "react-router-dom": "catalog:",
    "@monorepo/ui": "workspace:*",
    "@monorepo/utils": "workspace:*"
  },
  "devDependencies": {
    "webpack": "catalog:build",
    "babel": "catalog:build",
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/utils",
  "dependencies": {
    "react": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing"
  }
}

Actualizar versiones

Para actualizar versiones en todos los paquetes, simplemente cambia la versión en el package.json raíz:

"catalog": {
  "react": "^19.1.0",  // Actualizado desde ^19.0.0
  "react-dom": "^19.1.0"  // Actualizado desde ^19.0.0
}

Luego ejecuta bun install para actualizar todos los paquetes.

Integración con el lockfile

El lockfile de Bun rastrea versiones del catálogo, haciendo fácil asegurar instalaciones consistentes en diferentes entornos. El lockfile incluye:

• Las definiciones del catálogo desde tu package.json
• La resolución de cada dependencia catalogada

{
  "lockfileVersion": 1,
  "workspaces": {
    "": {
      "name": "react-monorepo",
    },
    "packages/app": {
      "name": "app",
      "dependencies": {
        "react": "catalog:",
        "react-dom": "catalog:",
        ...
      },
    },
    ...
  },
  "catalog": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    ...
  },
  "catalogs": {
    "build": {
      "webpack": "5.88.2",
      ...
    },
    ...
  },
  "packages": {
    ...
  }
}

Limitaciones y casos especiales

• Las referencias al catálogo deben coincidir con una dependencia definida en catalog o en uno de los catalogs con nombre
• Las cadenas vacías y espacios en blanco en nombres de catálogo se ignoran (se tratan como catálogo predeterminado)
• Las versiones de dependencias inválidas en los catálogos fallarán al resolverse durante bun install
• Los catálogos solo están disponibles dentro de espacios de trabajo; no pueden usarse fuera del monorepo

El sistema de catálogos de Bun proporciona una manera poderosa pero simple de mantener consistencia en todo tu monorepo sin introducir complejidad adicional a tu flujo de trabajo.

Publicación

Cuando ejecutas bun publish o bun pm pack, Bun reemplaza automáticamente las referencias catalog: en tu package.json con los números de versión resueltos. El paquete publicado incluye cadenas semver regulares y ya no depende de tus definiciones de catálogo.