توفر كتالوجات Bun طريقة مباشرة لمشاركة إصدارات التبعيات المشتركة عبر حزم متعددة في monorepo. بدلاً من تحديد نفس الإصدارات بشكل متكرر في كل حزمة مساحة عمل، يمكنك تحديدها مرة واحدة في package.json الجذر والرجوع إليها باستمرار في جميع أنحاء مشروعك.

نظرة عامة

على عكس إدارة التبعيات التقليدية حيث تحتاج كل حزمة مساحة عمل إلى تحديد الإصدارات بشكل مستقل، تتيح لك الكتالوجات:

1. تحديد كتالوجات الإصدارات في package.json الجذر
2. الرجوع إلى هذه الإصدارات باستخدام بروتوكول catalog: البسيط
3. تحديث جميع الحزم في وقت واحد عن طريق تغيير الإصدار في مكان واحد فقط

هذا مفيد بشكل خاص في monorepos الكبيرة حيث تحتاج عشرات الحزم إلى استخدام نفس الإصدار من التبعيات الرئيسية.

كيفية استخدام الكتالوجات

مثال على هيكل الدليل

فكر في monorepo بالهيكل التالي:

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

1. تحديد الكتالوجات في package.json الجذر

في package.json على المستوى الجذر، أضف حقل catalog أو catalogs داخل كائن 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"
      }
    }
  }
}

إذا وضعت catalog أو catalogs في المستوى الأعلى من ملف package.json، فسيكون ذلك جيدًا أيضًا.

2. الرجوع إلى إصدارات الكتالوج في حزم مساحة العمل

في حزم مساحة العمل الخاصة بك، استخدم بروتوكول catalog: للإشارة إلى الإصدارات:

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

قم بتشغيل bun install لتثبيت جميع التبعيات وفقًا لإصدارات الكتالوج.

Catalog مقابل Catalogs

يدعم Bun طريقتين لتحديد الكتالوجات:

1. catalog (مفرد): كتالوج افتراضي واحد للتبعيات شائعة الاستخدام

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

   الرجوع ببساطة باستخدام catalog::

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

2. catalogs (جمع): كتالوجات متعددة مسماة لتجميع التبعيات

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

   الرجوع باستخدام catalog:<name>:

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

فوائد استخدام الكتالوجات

• الاتساق: يضمن استخدام جميع الحزم لنفس الإصدار من التبعيات الحرجة
• الصيانة: تحديث إصدار التبعية في مكان واحد بدلاً من عبر ملفات package.json متعددة
• الوضوح: يجعل من الواضح أي التبعيات موحدة عبر monorepo الخاص بك
• البساطة: لا حاجة لاستراتيجيات حل الإصدارات المعقدة أو الأدوات الخارجية

مثال من العالم الحقيقي

إليك مثال أكثر شمولاً لتطبيق React:

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

تحديث الإصدارات

لتحديث الإصدارات عبر جميع الحزم، ما عليك سوى تغيير الإصدار في package.json الجذر:

"catalog": {
  "react": "^19.1.0",  // تم التحديث من ^19.0.0
  "react-dom": "^19.1.0"  // تم التحديث من ^19.0.0
}

ثم قم بتشغيل bun install لتحديث جميع الحزم.

تكامل Lockfile

يتتبع ملف قفل Bun إصدارات الكتالوج، مما يسهل ضمان التثبيت المتسق عبر البيئات المختلفة. يتضمن ملف القفل:

• تعريفات الكتالوج من package.json الخاص بك
• حل كل تبعية مفهرسة

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

القيود وحالات الحافة

• يجب أن تتطابق مراجع الكتالوج مع تبعية محددة في catalog أو أحد catalogs المسماة
• السلاسل الفارغة والمسافات البيضاء في أسماء الكتالوجات يتم تجاهلها (تُعامل ككتالوج افتراضي)
• إصدارات التبعيات غير الصالحة في الكتالوجات ستفشل في الحل أثناء bun install
• الكتالوجات متاحة فقط داخل مساحات العمل؛ لا يمكن استخدامها خارج monorepo

يوفر نظام الكتالوجات في Bun طريقة قوية وبسيطة للحفاظ على الاتساق عبر monorepo الخاص بك دون إدخال تعقيد إضافي إلى سير عملك.

النشر

عند تشغيل bun publish أو bun pm pack، يستبدل Bun تلقائيًا مراجع catalog: في package.json الخاص بك بأرقام الإصدارات المحلولة. تتضمن الحزمة المنشورة سلاسل semver عادية ولم تعد تعتمد على تعريفات الكتالوج الخاصة بك.