Les catalogues dans Bun fournissent un moyen simple de partager des versions de dépendances communes entre plusieurs packages dans un monorepo. Plutôt que de spécifier les mêmes versions à plusieurs reprises dans chaque package d'espace de travail, vous les définissez une fois dans le package.json racine et les référencez de manière cohérente dans tout votre projet.

Aperçu

Contrairement à la gestion traditionnelle des dépendances où chaque package d'espace de travail doit spécifier indépendamment les versions, les catalogues vous permettent de :

1. Définir des catalogues de versions dans le package.json racine
2. Référencer ces versions avec un simple protocole catalog:
3. Mettre à jour tous les packages simultanément en changeant la version à un seul endroit

Ceci est particulièrement utile dans les grands monorepos où des dizaines de packages doivent utiliser la même version de dépendances clés.

Comment utiliser les catalogues

Exemple de structure de répertoire

Considérons un monorepo avec la structure suivante :

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

1. Définir les catalogues dans le package.json racine

Dans votre package.json de niveau racine, ajoutez un champ catalog ou catalogs dans l'objet 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 vous placez catalog ou catalogs au niveau supérieur du fichier package.json, cela fonctionnera également.

2. Référencer les versions du catalogue dans les packages d'espace de travail

Dans vos packages d'espace de travail, utilisez le protocole catalog: pour référencer les versions :

{
  "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. Exécuter Bun Install

Exécutez bun install pour installer toutes les dépendances selon les versions du catalogue.

Catalog vs Catalogs

Bun prend en charge deux façons de définir les catalogues :

1. catalog (singulier) : Un catalogue par défaut unique pour les dépendances couramment utilisées

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

   Référencez simplement avec catalog: :

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

2. catalogs (pluriel) : Plusieurs catalogues nommés pour regrouper les dépendances

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

   Référencez avec catalog:<nom> :

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

Avantages de l'utilisation des catalogues

• Cohérence : Garantit que tous les packages utilisent la même version de dépendances critiques
• Maintenance : Mettez à jour une version de dépendance à un seul endroit au lieu de plusieurs fichiers package.json
• Clarté : Rend évident quelles dépendances sont standardisées dans tout votre monorepo
• Simplicité : Pas besoin de stratégies de résolution de versions complexes ou d'outils externes

Exemple concret

Voici un exemple plus complet pour une application React :

package.json racine

{
  "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"
  }
}

Mise à jour des versions

Pour mettre à jour les versions dans tous les packages, changez simplement la version dans le package.json racine :

"catalog": {
  "react": "^19.1.0",  // Mis à jour depuis ^19.0.0
  "react-dom": "^19.1.0"  // Mis à jour depuis ^19.0.0
}

Puis exécutez bun install pour mettre à jour tous les packages.

Intégration avec le lockfile

Le lockfile de Bun suit les versions du catalogue, ce qui facilite l'assurance d'installations cohérentes dans différents environnements. Le lockfile inclut :

• Les définitions de catalogue depuis votre package.json
• La résolution de chaque dépendance cataloguée

{
  "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": {
    ...
  }
}

Limitations et cas particuliers

• Les références de catalogue doivent correspondre à une dépendance définie dans soit catalog soit l'un des catalogs nommés
• Les chaînes vides et les espaces dans les noms de catalogue sont ignorés (traités comme catalogue par défaut)
• Les versions de dépendances invalides dans les catalogues échoueront lors de la résolution pendant bun install
• Les catalogues sont uniquement disponibles dans les espaces de travail ; ils ne peuvent pas être utilisés en dehors du monorepo

Le système de catalogue de Bun fournit un moyen puissant mais simple de maintenir la cohérence dans tout votre monorepo sans introduire de complexité supplémentaire dans votre flux de travail.

Publication

Lorsque vous exécutez bun publish ou bun pm pack, Bun remplace automatiquement les références catalog: dans votre package.json par les numéros de version résolus. Le package publié inclut des chaînes semver régulières et ne dépend plus de vos définitions de catalogue.