النشر إلى npm والإصدارات الدلالية

قبل النشر، شغّل دائمًا npm publish --dry-run. يحاكي هذا عملية النشر دون رفع أي شيء فعليًا، ويعرض لك بالضبط الملفات التي ستُضمَّن وأحجامها ومحتويات أرشيف الحزمة. كما يكشف الأخطاء الشائعة، مثل تضمين ملفات المصدر عن طريق الخطأ أو عدم تضمين مجلد dist.

تحكّم في ما يُنشر باستخدام الحقل files في package.json: "files": ["dist", "README.md"]. يُعد هذا الأسلوب القائم على قائمة السماح أكثر أمانًا من .npmignore، الذي يعمل بقائمة حظر وقد يؤدي إلى تسريب ملفات حساسة إذا نسيت إضافتها. احرص دائمًا على تضمين dist وتصريحات الأنواع والتوثيق. ولا تُضمّن مطلقًا src أو tests أو node_modules.

تتبع حزم npm الإصدار الدلالي (semver): MAJOR.MINOR.PATCH. زِد MAJOR عند إجراء تغييرات غير متوافقة، مثل إزالة props أو تغيير توقيعات API. وزِد MINOR عند إضافة ميزات جديدة متوافقة مع الإصدارات السابقة، مثل مكوّنات جديدة أو props اختيارية جديدة. وزِد PATCH لإصلاح الأخطاء مع الحفاظ على التوافق مع الإصدارات السابقة. ويُعد الإصدار 0.x.x إصدارًا أوليًا غير مستقر، إذ يمكن أن يتغير فيه أي شيء.

تشير معرّفات ما قبل الإطلاق إلى أن الإصدار غير جاهز للاستخدام في الإنتاج: 1.0.0-alpha.1 للإصدارات التجريبية المبكرة، و1.0.0-beta.2 للإصدارات المكتملة الميزات لكن التي قد تحتوي على أخطاء، و1.0.0-rc.1 (المرشح للإصدار النهائي) للإصدارات الجاهزة للاختبار النهائي. انشر إصدارات ما قبل الإطلاق باستخدام npm publish --tag beta حتى لا تصبح الإصدار الافتراضي عند التثبيت.

تُعد Changesets الأداة القياسية لإدارة إصدارات الحزم وسجلات التغييرات في مكتبات المكوّنات. سير العمل هو: يشغّل المساهمون yarn changeset add لتسجيل ما تغيّر ونوع التغيير (major/minor/patch). ثم يشغّل CI الأمر yarn changeset version لزيادة إصدارات الحزم. وأثناء النشر، يُشغّل الأمر yarn changeset publish لدفع الحزم إلى npm.

تولّد Changesets ملف CHANGELOG.md وتحدّثه تلقائيًا استنادًا إلى ملفات changeset التي يلتزم بها المساهمون. يتضمن كل إدخال رقم الإصدار وتاريخ الإصدار ووصف التغييرات. وينشئ ذلك سجلًا سهل القراءة لكل إصدار، دون الحاجة إلى صيانة سجل التغييرات يدويًا.

إن semantic-release أداة مؤتمتة بالكامل لإدارة الإصدارات، إذ تحدد الإصدار التالي من رسائل الالتزام التقليدية (feat: ← minor، وfix: ← patch، وBREAKING CHANGE: ← major). كما تزيد رقم الإصدار وتولّد سجل التغييرات وتنشر الحزمة إلى npm، وكل ذلك يُشغّله CI عند الدمج في main. لا حاجة إلى إدارة الإصدارات يدويًا.

تكون الحزم غير المقيّدة النطاق (my-component) عامة دائمًا. أما الحزم المقيّدة النطاق (@myorg/my-component) فتكون مقيّدة افتراضيًا (خاصة)، لذا انشرها للعامة باستخدام npm publish --access public. تتطلب الحزم المقيّدة حساب npm مدفوعًا أو مؤسسة. تأكد من إعدادات الوصول قبل أول عملية نشر.

يربط إثبات منشأ npm الحزمة المنشورة بالتزام git المحدد الخاص بها بطريقة قابلة للتحقق. فعّله باستخدام npm publish --provenance في GitHub Actions. ويمكن للمستخدمين التحقق من أن الحزمة التي ثبّتوها بُنيت من التزام المصدر نفسه المعروض في صفحة الحزمة على سجل npm. ويعزز ذلك أمان سلسلة التوريد بدرجة كبيرة.

عندما يحتوي إصدار ما على خطأ حرج أو تغيير غير متوافق، أهمله باستخدام: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". يعرض npm تحذيرًا بشأن الإهمال لأي شخص يثبّت ذلك الإصدار. ولا يؤدي هذا إلى إزالة الإصدار؛ إذ لا يحذف npm الإصدارات المنشورة افتراضيًا، لكنه ينبه المستخدمين إلى الترقية.

تستخدم الحزم المقيّدة النطاق الصيغة @scope/package-name. ويكون النطاق عادةً اسم مستخدمك في npm أو اسم مؤسستك. توضّح الحزم المقيّدة النطاق الجهة التي تتولى صيانة الحزمة، وتمنع تعارضات الأسماء مع الحزم غير المقيّدة النطاق. استخدمها للحزم الخاصة ولحزم المصدر المفتوح المرتبطة بمؤسستك.

وفقًا للإصدار الدلالي، متى يجب زيادة رقم الإصدار MAJOR؟

استخدم npm publish --dry-run لمعاينة ما سيُنشر، واستخدم الحقل files للتحكم في الملفات المنشورة. في الإصدار الدلالي: يشير MAJOR إلى التغييرات غير المتوافقة، وMINOR إلى الميزات الجديدة، وPATCH إلى الإصلاحات. تستخدم الإصدارات السابقة للإطلاق الوسوم -alpha/-beta/-rc. تعمل Changesets على أتمتة إدارة الإصدارات وتوليد CHANGELOG للمكتبات التعاونية. وتؤتمت semantic-release العملية انطلاقًا من الالتزامات التقليدية. فعّل --provenance لتعزيز أمان سلسلة التوريد. وأهمل الإصدارات التي تحتوي على أخطاء باستخدام npm deprecate.