catalogs

15 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Define catalogs with catalog (singular) or catalogs (plural) fields

Catalogs can be defined in the root package.json within the workspaces object, or at the top level of package.json. The catalog field (singular) defines a single default catalog for commonly used dependencies. The catalogs field (plural) defines multiple named catalogs for grouping dependencies by category.

Catalogs share dependency versions across monorepo packages

Catalogs allow you to define version numbers once in the root package.json and reference them throughout workspace packages using the catalog: protocol. This eliminates repeating the same versions in each workspace package and enables updating every package at once by changing the version in one place.

Reference default catalog with catalog: protocol

In workspace packages, reference versions from the default catalog using the catalog: protocol without a name. For example, setting a dependency to "catalog:" will use the version defined in the root package.json catalog field.

Reference named catalogs with catalog:name syntax

For named catalogs defined in the catalogs field, reference them using the catalog:<name> syntax. For example, to reference the testing catalog, use "catalog:testing" as the version string.

Default catalog field syntax

The default catalog is defined as a flat object: "catalog": { "react": "^19.0.0", "react-dom": "^19.0.0" }

Named catalogs field syntax

Named catalogs are defined as nested objects: "catalogs": { "testing": { "jest": "30.0.0", "testing-library": "14.0.0" }, "ui": { "tailwind": "4.0.0" } }

Example workspace package using catalog references

In workspace packages, reference catalog versions like this: { "name": "app", "dependencies": { "react": "catalog:", "react-dom": "catalog:", "jest": "catalog:testing" } }

Update catalog versions by modifying root package.json

To update versions across all packages, change the version in the root package.json catalog or catalogs field, then run bun install. All workspace packages using that catalog reference will be updated automatically.

Lockfile includes catalog definitions and resolutions

Bun's lockfile tracks catalog versions for consistency across environments. The lockfile includes the catalog definitions from package.json and the resolution of each cataloged dependency, ensuring installs are reproducible.

Catalog references must be defined in catalog or catalogs

Catalog references in workspace packages must match a dependency defined in either the default catalog field or one of the named catalogs. References to undefined catalog entries will fail to resolve during bun install.

Empty strings and whitespace in catalog names treated as default

When defining named catalogs, empty strings and whitespace in catalog names are ignored and treated as references to the default catalog.

Catalogs only available within monorepo workspaces

Catalogs cannot be used outside of workspaces. They are only available for monorepo dependency management within the workspace structure.

bun publish replaces catalog: references with resolved versions

When you run bun publish or bun pm pack, Bun automatically replaces catalog: references in package.json with the resolved version numbers. The published package includes regular semver strings and no longer depends on catalog definitions.

Run bun install to install dependencies using catalog versions

After defining catalogs and referencing them in workspace packages, run bun install to install all dependencies according to the catalog versions specified.

Catalogs for shared dependency versions

When many packages need the same dependency versions, define those versions once in a catalog in the root package.json and reference them from workspaces with the catalog: protocol. Updating the catalog updates every package that references it.

Give your agent this brain