RFC: BunCatalogManager — Bun Dependency Catalog Support for Nx

[yrybak-op8]

Summary

Nx already ships package-manager-specific catalog managers for pnpm (PnpmCatalogManager) and Yarn (YarnCatalogManager). This RFC proposes adding a BunCatalogManager that brings Bun catalog support to the same level of integration.

Bun catalog docs: https://bun.com/docs/pm/catalogs
pnpm manager: packages/nx/src/utils/catalog/pnpm-manager.ts
Yarn manager: packages/nx/src/utils/catalog/yarn-manager.ts

---

Motivation

Nx supports Bun as a package manager, but the dependency catalog system in packages/nx/src/utils/catalog/ does not cover Bun. The getCatalogManager factory in manager-factory.ts currently returns null for Bun workspaces:

// packages/nx/src/utils/catalog/manager-factory.ts
switch (packageManager) {
  case 'pnpm':
    return new PnpmCatalogManager();
  case 'yarn':
    return new YarnCatalogManager();
  default:
    return null; // <-- Bun falls through here
}

As a result, any catalog: reference in a Bun workspace is silently left unresolved by resolveCatalogReferenceIfNeeded, resolveCatalogSpecifiers, and getCatalogDependenciesFromPackageJson. This breaks:

• dependency version resolution in the project graph
• @nx/dependency-checks lint rule
• nx migrate catalog version updates
• generators that read, add, or update dependencies

---

Bun Catalog Format

Bun stores catalog definitions inside the root package.json, not in a separate file. It supports four locations, all of which must be handled:

// Variant A — nested under "workspaces" object
{
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0"
    },
    "catalogs": {
      "react18": { "react": "^18.3.0" }
    }
  }
}

// Variant B — top-level shorthand (mirrors pnpm's top-level "catalog")
{
  "catalog": {
    "react": "^19.0.0"
  },
  "catalogs": {
    "react18": { "react": "^18.3.0" }
  }
}

Workspace package references use the same catalog: protocol as pnpm and Yarn:

{
  "dependencies": {
    "react": "catalog:",           // default catalog
    "react": "catalog:react18"    // named catalog
  }
}

The lookup priority when both workspaces.catalog and a top-level catalog are present should follow Bun's own resolution order (workspaces-nested takes precedence when the workspaces field is an object).

---

What Needs to Change

1. New file: packages/nx/src/utils/catalog/bun-manager.ts

The implementation follows the exact same structure as PnpmCatalogManager and YarnCatalogManager. The key differences are:

Aspect	pnpm	Yarn	Bun
Config file	pnpm-workspace.yaml	.yarnrc.yml	package.json
Serialisation	YAML (@zkochan/js-yaml)	YAML (@zkochan/js-yaml)	JSON
Catalog locations	catalog / catalogs	catalog / catalogs	workspaces.catalog, workspaces.catalogs, top-level catalog, top-level catalogs

getCatalogDefinitions must merge both location variants into the shared CatalogDefinitions shape:

// packages/nx/src/utils/catalog/bun-manager.ts (sketch)
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { Tree } from '../../generators/tree';
import { readJson } from '../../generators/utils/json';
import { output } from '../output';
import { formatCatalogError, type CatalogManager } from './manager';
import type { CatalogDefinitions, CatalogEntry, CatalogReference } from './types';

const PKG_JSON = 'package.json';

export class BunCatalogManager implements CatalogManager {
  readonly name = 'bun';
  readonly catalogProtocol = 'catalog:';

  // isCatalogReference / parseCatalogReference — identical to pnpm/yarn
  // resolveCatalogReference / validateCatalogReference — identical logic

  getCatalogDefinitionFilePaths(): string[] {
    return [PKG_JSON];
  }

  getCatalogDefinitions(treeOrRoot: Tree | string): CatalogDefinitions | null {
    // Read package.json, then normalise the four Bun locations into
    // { catalog?, catalogs? } — the shape CatalogDefinitions already expects.
    // workspaces.catalog / workspaces.catalogs take priority over top-level.
  }

  updateCatalogVersions(treeOrRoot, updates): void {
    // Read package.json as JSON (not YAML), apply updates,
    // write back with JSON.stringify(data, null, 2).
    // Must preserve whichever catalog location already exists.
  }
}

function normaliseBunCatalogs(pkg: any): CatalogDefinitions {
  const ws = pkg.workspaces;
  const fromWorkspaces =
    ws && typeof ws === 'object' && !Array.isArray(ws)
      ? { catalog: ws.catalog, catalogs: ws.catalogs }
      : {};

  const fromTopLevel = { catalog: pkg.catalog, catalogs: pkg.catalogs };

  return {
    catalog: fromWorkspaces.catalog ?? fromTopLevel.catalog,
    catalogs: fromWorkspaces.catalogs ?? fromTopLevel.catalogs,
  };
}

Important: updateCatalogVersions must write back to package.json using JSON, not YAML. It also must not clobber unrelated fields — only update the specific catalog or catalogs key that was the source of the resolved definition.

2. Register in manager-factory.ts

import { BunCatalogManager } from './bun-manager';

export function getCatalogManager(workspaceRoot: string): CatalogManager | null {
  switch (detectPackageManager(workspaceRoot)) {
    case 'pnpm': return new PnpmCatalogManager();
    case 'yarn': return new YarnCatalogManager();
    case 'bun':  return new BunCatalogManager();  // ← add this
    default:     return null;
  }
}

3. New test file: packages/nx/src/utils/catalog/bun-manager.spec.ts

Should mirror the structure of pnpm-manager.spec.ts and yarn-manager.spec.ts, with additional test cases covering:

• Bun's four catalog location variants
• Priority when both workspaces.catalog and top-level catalog are present
• updateCatalogVersions writing valid JSON back to package.json without destroying unrelated fields

---

Scope of Integration

Once getCatalogManager returns a BunCatalogManager, the following already-wired call sites get Bun support for free — no further changes needed:

Call site	File
resolveCatalogReferenceIfNeeded	packages/nx/src/utils/catalog/index.ts
resolveCatalogSpecifiers	packages/nx/src/utils/catalog/index.ts
getCatalogDependenciesFromPackageJson	packages/nx/src/utils/catalog/index.ts
@nx/dependency-checks lint rule	uses resolveCatalogSpecifiers
nx migrate catalog updates	uses updateCatalogVersions
Generators reading/writing deps	use resolveCatalogReferenceIfNeeded

---

Feedback Requested

1. Is a dedicated BunCatalogManager the right abstraction, or should the common catalog: logic be extracted into a shared base class that pnpm/Yarn/Bun all extend?
2. How should conflict detection between workspaces.catalog and top-level catalog behave — hard error or silent preference?
3. Are there Bun-specific behaviors (e.g. catalog resolution order, catalog:default alias) that differ from pnpm and need special casing?