لمحاذاة تبعية ما عبر حزم npm على جهاز Mac، قارن أولاً نطاقات الإصدارات في ملف package.json الخاص بكل مساحة عمل (workspace)، وحدد نطاق الإصدار المشترك المناسب لكل حزمة، ثم حدّث كل مساحة عمل متأثرة وأعد إنشاء ملف القفل (lockfile) الجذري. تتيح مساحات عمل npm استهداف الحزم من جذر المستودع، لكنها لا توفر أمرًا مدمجًا يفحص كل بيان (manifest) ويجعل إصدارات التبعيات متطابقة تلقائيًا.

1. التحقق من أن المستودع يستخدم مساحات عمل npm

في تطبيق Terminal، انتقل إلى جذر المستودع وافحص تهيئته:

cd "/path/to/your/repository"
npm --version
npm pkg get workspaces

يجب أن يحدد ملف package.json الجذري مسارات مساحات العمل، ويجب أن تحتوي كل حزمة على ملف package.json خاص بها. تعمل ميزة مساحات العمل في npm على ربط تلك الحزم المحلية أثناء التثبيت وتتيح للأوامر استهداف مساحة عمل واحدة أو أكثر بالاسم أو المسار. إذا لم يُرجع الأمر npm pkg get workspaces أي شيء، فتأكد من مدير الحزم في المستودع ومخططه الهيكلي قبل استخدام أوامر مساحات عمل npm. مساحات عمل npm

2. مقارنة تصريحات التبعيات

ابحث في البيانات (manifests) المتتبعة عن التبعية التي ترغب في محاذاتها. على سبيل المثال، في Terminal الخاص بنظام macOS، يمكنك استخدام grep دون تثبيت أي أداة إضافية:

grep -n '"typescript"' package.json packages/*/package.json

استبدل typescript باسم التبعية. هذا فحص نصي سريع، لذا راجع الأقسام المتطابقة في كل بيان لمعرفة ما إذا كانت الحزمة مدرجة تحت dependencies أو devDependencies أو peerDependencies أو optionalDependencies. تصف هذه الحقول أدوارًا مختلفة؛ لا تنقل تبعية بينها لمجرد جعل نصوص الإصدارات متطابقة. للحصول على جرد أكثر اكتمالاً، افحص بيان كل مساحة عمل في محررك أو استخدم أمر السرد المدرك لمساحات العمل في npm:

npm ls typescript --workspaces --depth=0

تجيب نطاقات البيان وشجرة التثبيت عن أسئلة مختلفة: يُظهر الأول ما تسمح به كل حزمة، بينما يوضح npm ls حالة التبعية المثبتة. يسجل ملف قفل npm الإصدارات التي تم حلها، ولكنه لا يحل محل النطاقات المقبولة المصرح بها في كل ملف package.json. npm ls package-lock.json و npm install

3. اختيار سياسة إصدار متوافقة

اختر إصدارًا يلبي متطلبات المستخدمين (consumers) وسياسة الدعم الخاصة بالمستودع. يعني نطاق الإصدار المشترك أن الحزم تعبر عن نفس المجموعة المسموح بها؛ ولا يضمن ذلك أن تُحل جميع النسخ المتداخلة أو المتعدية إلى نسخة مثبتة واحدة. تحقق من متطلبات التبعيات النظيرة (peer dependencies) وملاحظات الإصدار لمعرفة التغييرات الجذرية (breaking changes) قبل ترقية الحزم عبر إصدار رئيسي (major version). إذا كان المستخدمون بحاجة إلى نطاق توافق أوسع، فقد تكون المحاذاة إلى نفس النص الدقيق غير ملائمة؛ اتفق على سياسة نطاق مكافئة بدلاً من ذلك.

على سبيل المثال، لتعيين أداة تطوير على نفس الإصدار الدقيق في مساحتي عمل باسم web و api، شغّل هذا الأمر من الجذر:

npm install --save-dev --save-exact typescript@5.8.3 --workspace=web --workspace=api

استخدم الإصدار الذي حدده مشروعك؛ الإصدار 5.8.3 هنا هو مجرد مثال. يقبل أمر تثبيت npm محددات مساحات العمل ويحفظ الحزمة في بيان كل حزمة محددة. يكتب الخيار --save-exact إصدارًا محددًا بدلاً من معامل النطاق المعتاد في npm. بالنسبة لتبعية وقت التشغيل (runtime dependency)، استخدم فئة الحفظ المناسبة، مثل --save-prod، بدلاً من --save-dev. npm install

كرر ذلك مع محددات مساحات عمل إضافية أو نفّذ الأمر لكل مساحة عمل. لا تفترض أن التثبيت على مستوى الجذر يُحدّث بيان كل حزمة: استهدف بشكل صريح الحزم التي يجب تغيير تصريحاتها. يمكن أيضًا تضمين الحزمة الجذرية عمدًا باستخدام الخيار --include-workspace-root عندما يُفترض بها التصريح عن نفس التبعية.

4. إعادة التثبيت، وفحص الفروق (diff)، والتحقق

بعد تحديث التصريحات، شغّل التثبيت في جذر المستودع حتى يقوم npm بتسوية شجرة مساحات العمل وملف القفل:

npm install
npm ls typescript --workspaces --depth=0
git diff -- package.json package-lock.json packages/*/package.json

تأكد من أن كل بيان مستهدف يحتوي على التصريح المتفق عليه وأن التغيير في ملف القفل متوقع. شغّل نصوص البناء (build) أو الاختبار ذات الصلة في المستودع؛ فالأمر npm ls وحده لا يثبت أن الكود يعمل مع الإصدار المحدد. قم بعمل commit لملف package-lock.json الجذري عندما يتتبعه المشروع، حتى تتمكن عمليات التثبيت لدى الفريق من إعادة إنتاج الشجرة المحلولة ذاتها. توثيق npm لملف package-lock

إذا أبلغ npm عن تبعية غير صالحة أو تعارض في التبعيات النظيرة (peer conflict)، فافحص الحزمة المذكورة في الخطأ بدلاً من فرض التثبيت. قد تتطلب إحدى مساحات العمل نطاق توافق مختلفًا، أو قد تفرض تبعية أخرى متطلبًا نظيرًا يحتاج إلى خطة ترقية مدروسة.

متى يفيد استخدام npm dedupe

يمكن لأمر npm dedupe تبسيط شجرة التبعيات المثبتة عن طريق نقل التبعيات المتوافقة إلى مستوى أعلى حتى تتمكن الحزم من مشاركتها. إنه لا يُعيد كتابة نطاقات التبعيات المباشرة في ملف package.json، وبالتالي لا يمكنه محاذاة التصريحات بمفرده. استخدمه فقط بعد التأكد من توافق النطاقات، ثم راجع الفروق (diff) الناتجة في ملف القفل. npm dedupe

إن النهاية الموثوقة تتمثل في وجود سياسة مدروسة يتم التعبير عنها في بيان كل مساحة عمل ذات صلة، وملف قفل يُعاد إنشاؤه، والتحقق من الحزم المتأثرة. يمنح ذلك مسؤولي الصيانة سجلاً واضحًا لما تمّت محاذاته ويترك القيود غير المتوافقة مرئية لاتخاذ قرار منفصل بشأنها.

المصادر