كيفية نشر حزم NPM الخاصة بالشركة على GitLab؟ دليل إعداد pnpm الكامل

تخيل أنك رئيس طهاة. لضمان أن جميع المطاعم في سلسلتك تنتج نفس الأطباق اللذيذة، قمت بتطوير سلسلة من “الصلصات السرية”. تريد إرسال هذه الصلصات إلى كل فرع، لكن لا يمكنك السماح للمارة العاديين بأخذها.

في عالم تطوير البرمجيات، هذه الصلصات السرية هي “الحزم الخاصة” (private packages) الداخلية للشركة.

مع نمو المشاريع، من المحتمل أنك واجهت هذا الإحباط: تكرار نفس مكون واجهة المستخدم أو وظيفة الأداة المساعدة عبر كل مشروع، أو المعاناة مع Git Submodules حتى تشك في خياراتك الحياتية. في الواقع، كل ما تحتاجه هو “مخزن مؤن خاص (Private NPM Registry)”. اليوم، سنناقش كيفية استخدام pnpm لنشر الحزم على GitLab، حتى يتمكن أعضاء الفريق من تثبيتها تمامًا مثل الحزم مفتوحة المصدر بأمر واحد فقط.

لماذا تحتاج إلى حزم خاصة ونطاقات (Scopes)؟

في عالم Node.js، يجب أن يكون للحزم الخاصة “لقب” (Surname)—هذا هو الـ Scope.

على سبيل المثال، إذا كان اسم شركتك هو @my-company، فقد يبدو اسم حزمتك كما يلي: @my-company/ui-kit. بهذا اللقب، عندما تراها أداة pnpm لن تبحث عشوائيًا في npmjs.org. بدلاً من ذلك، ستتجه مباشرة إلى نقاط التنسيق الخاصة بشركتك التي حددتها.

القرار الرئيسي: مستوى المجموعة (Group Level) مقابل مستوى المشروع (Project Level)

في GitLab، يشبه هذا تحديد مكان تخزين توابلك:

المستوى	الوصف
مستوى المشروع	مثل الخزنة الشخصية للطاهي، قابلة للاستخدام لأطباق محددة فقط. إعدادها أكثر صعوبة لأن كل حزمة تتطلب تكوينًا مستقلاً.
مستوى المجموعة	هذا هو مفهوم “المطبخ المركزي”—يوصى به بشدة! قم بإعداده مرة واحدة، ويمكن لعشرات أو حتى مئات الحزم تحت نفس المجموعة مشاركة نفس الإعدادات وبيانات الاعتماد.

إعداد “جواز السفر”: رموز الوصول (Access Tokens) ومتغيرات البيئة

للدخول إلى مخزن الحبوب تحت الأرض، تحتاج أولاً إلى الحصول على “بطاقة وصول”.

انتقل إلى Settings > Access Tokens في GitLab.
تقدم بطلب للحصول على رمز (Token)، مع تحديد أذونات read_api (للتنزيل) و write_package_registry (للنشر).
هام: بمجرد حصولك على الرمز، لا تضعه أبدًا مباشرة في التعليمات البرمجية الخاصة بك أو في ملف .npmrc! هذا يشبه ترك مفتاح الخزنة في الباب.

النهج الأكثر احترافية هو إخفاؤه في “متغيرات البيئة”. أضف هذا السطر إلى محطة Mac أو Linux (على سبيل المثال، ~/.zshrc):

export GITLAB_TOKEN="الرمز_الخاص_بك_من_GitLab"

بهذه الطريقة، سيقوم النظام تلقائيًا بإرفاق بيانات الاعتماد لك، مما يجعل الأمر آمنًا ومريحًا في نفس الوقت.

إعدادات التنقل: جوهر ملف `.npmrc`

بعد ذلك، سنقوم لإنشاء خريطة تنقل، .npmrc ، في جذر المشروع لإخبار pnpm إلى أين يجب أن يذهب:

# لأي شيء يبدأ بـ @my-company ، اذهب إلى GitLab
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/

# إعداد مصادقة بطاقة الوصول (قراءة متغير البيئة الذي قمنا بتعيينه للتو)
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"

ما عليك سوى استبدال معرف المجموعة (Group ID) الخاص بشركتك، وسيصبح الطريق ممهدًا!

الميل الأخير قبل النشر: فن التغليف

يركض الكثير من الناس للنشر بعد إعداد الاتصال، فقط ليقوموا عن غير قصد بتحميل ملفات الاختبار أو حتى التكوينات السرية. هذا هو المكان الذي يأتي فيه حقل files في ملف package.json كأداة مفيدة.

هذا هو مفهوم “قائمة السماح” (allowlist):

{
  "name": "@my-company/lib-1",
  "files": [
    "dist"
  ],
  "publishConfig": {
    "registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
  }
}

الإعداد	الوصف
`files`	أخبر النظام صراحةً أنني أريد فقط نشر الجوهر المترجم داخل مجلد `dist` ، وترك كل الفوضى الأخرى خلفي.
`publishConfig`	هذا تأمين مزدوج، يضمن عدم نشر هذه الحزمة عن طريق الخطأ في المكان العام (npmjs.org).

قبل النشر، يوصى باستخدام أمر pnpm pack لفتح الحزمة والتحقق من المحتوى محليًا. بمجرد أن يبدو كل شيء جيدًا، قم بتشغيل pnpm publish بثقة!

الخاتمة

إن بناء مخزن مؤن خاص ليس أمرًا صعبًا. المفاتيح هي:

اطلب رمزًا (Token) واحمِه بمتغيرات البيئة.
قم بتكوين خريطة التنقل الصحيحة في ملف .npmrc.
استخدم حقل files في ملف package.json للشحن الدقيق.

من خلال إتقان سير العمل هذا، يمكنك جعل إعادة استخدام كود شركتك احترافيًا وآمنًا وأنيقًا. الآن، اذهب وابنِ مطبخك المركزي الخاص!