Kataloge in Bun bieten eine einfache Möglichkeit, gemeinsame Abhängigkeitsversionen über mehrere Pakete in einem Monorepo zu teilen. Anstatt dieselben Versionen in jedem Workspace-Paket wiederholt anzugeben, definieren Sie sie einmalig in der root package.json und verweisen konsistent im gesamten Projekt darauf.

Übersicht

Im Gegensatz zur traditionellen Abhängigkeitsverwaltung, bei der jedes Workspace-Paket Versionen unabhängig angeben muss, ermöglichen Kataloge Ihnen:

1. Versionskataloge in der root package.json zu definieren
2. Mit einem einfachen catalog:-Protokoll auf diese Versionen zu verweisen
3. Alle Pakete gleichzeitig zu aktualisieren, indem die Version an nur einer Stelle geändert wird

Dies ist besonders nützlich in großen Monorepos, in denen Dutzende von Paketen dieselbe Version wichtiger Abhängigkeiten verwenden müssen.

Verwendung von Katalogen

Verzeichnisstruktur-Beispiel

Betrachten Sie ein Monorepo mit folgender Struktur:

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

1. Kataloge in der root package.json definieren

Fügen Sie in Ihrer root package.json ein catalog- oder catalogs-Feld innerhalb des workspaces-Objekts hinzu:

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

Wenn Sie catalog oder catalogs auf der obersten Ebene der package.json-Datei platzieren, funktioniert das ebenfalls.

2. In Workspace-Paketen auf Katalogversionen verweisen

Verwenden Sie in Ihren Workspace-Paketen das catalog:-Protokoll, um auf Versionen zu verweisen:

{
  "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. Bun Install ausführen

Führen Sie bun install aus, um alle Abhängigkeiten gemäß den Katalogversionen zu installieren.

Catalog vs Catalogs

Bun unterstützt zwei Möglichkeiten, Kataloge zu definieren:

1. catalog (Singular): Ein einzelner Standardkatalog für häufig verwendete Abhängigkeiten

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

   Einfach mit catalog: referenzieren:

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

2. catalogs (Plural): Mehrere benannte Kataloge zum Gruppieren von Abhängigkeiten

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

   Mit catalog:<name> referenzieren:

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

Vorteile der Verwendung von Katalogen

• Konsistenz: Stellt sicher, dass alle Pakete dieselbe Version kritischer Abhängigkeiten verwenden
• Wartung: Aktualisieren Sie eine Abhängigkeitsversion an einer Stelle statt über mehrere package.json-Dateien
• Klarheit: Macht offensichtlich, welche Abhängigkeiten im gesamten Monorepo standardisiert sind
• Einfachheit: Keine komplexen Versionsauflösungsstrategien oder externen Tools erforderlich

Praxisbeispiel

Hier ist ein umfassenderes Beispiel für eine React-Anwendung:

Root package.json

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

Versionen aktualisieren

Um Versionen über alle Pakete hinweg zu aktualisieren, ändern Sie einfach die Version in der root package.json:

"catalog": {
  "react": "^19.1.0",  // Aktualisiert von ^19.0.0
  "react-dom": "^19.1.0"  // Aktualisiert von ^19.0.0
}

Führen Sie dann bun install aus, um alle Pakete zu aktualisieren.

Lockfile-Integration

Buns Lockfile verfolgt Katalogversionen und ermöglicht so konsistente Installationen in verschiedenen Umgebungen. Die Lockfile enthält:

• Die Katalogdefinitionen aus Ihrer package.json
• Die Auflösung jeder katalogisierten Abhängigkeit

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

Einschränkungen und Grenzfälle

• Katalogreferenzen müssen einer Abhängigkeit entsprechen, die entweder in catalog oder einem der benannten catalogs definiert ist
• Leere Strings und Leerzeichen in Katalognamen werden ignoriert (als Standardkatalog behandelt)
• Ungültige Abhängigkeitsversionen in Katalogen können während bun install nicht aufgelöst werden
• Kataloge sind nur innerhalb von Workspaces verfügbar; sie können nicht außerhalb des Monorepo verwendet werden

Buns Katalogsystem bietet eine leistungsstarke, aber einfache Möglichkeit, Konsistenz über Ihr Monorepo hinweg aufrechtzuerhalten, ohne zusätzliche Komplexität in Ihren Workflow einzuführen.

Veröffentlichen

Wenn Sie bun publish oder bun pm pack ausführen, ersetzt Bun automatisch catalog:-Referenzen in Ihrer package.json durch die aufgelösten Versionsnummern. Das veröffentlichte Paket enthält reguläre Semver-Strings und hängt nicht mehr von Ihren Katalogdefinitionen ab.