«npm WARN requires a peer»: كيفية إصلاح وفهم جوهر الخطأ

مقدمة: لماذا يصرخ npm عليك؟

هل سبق لك أن قمت بتشغيل npm install\n\n

npm WARN ts-patch@3.2.1 requires a peer of typescript@>=4.0 but none is installed. You must install peer dependencies yourself.

مألوف؟ إذا كان الأمر كذلك، فأنت لست وحدك. هذا السؤال على Stack Overflow حصد آلاف المشاهدات وعشرات التعليقات من مطورين، مثلك تمامًا، أرادوا فقط تثبيت حزمة، لكنهم حصلوا على صداع. اليوم سنفهم ما هي التبعيات النظيرة (peer dependencies)، ولماذا يصر npm بشدة على تثبيتها، وكيفية التعامل معها بشكل صحيح في مشاريع TypeScript. ونعم، لن تكون هذه وثائق مملة، بل تحليلًا حيًا مع أمثلة على الكود.

هيا بنا!

ما هي التبعيات النظيرة ولماذا هي مطلوبة؟

تخيل أنك تقوم بتجميع أحجية (puzzle). لديك الصورة الرئيسية (مشروعك) وعدة قطع (حزم). بعض القطع تتناسب تمامًا مع بعضها البعض، ولكن فقط إذا كنت تستخدم الإطار الصحيح. في عالم npm، هذا «الإطار» هو التبعية النظيرة (peer dependency).

التبعية النظيرة هي متطلب من حزمة بأن مكتبة معينة يجب أن تكون مثبتة في المشروع، لكن الحزمة نفسها لن تقوم بتثبيتها. لماذا؟ لأن هذه المكتبة يجب أن تكون موجودة لديك بالفعل، والحزمة ببساطة «تتعامل» معها دون إنشاء نسخ مكررة.

على سبيل المثال، الحزمة ts-patch (أداة شائعة لـ TypeScript) تتطلب أن يكون typescript مثبتًا في المشروع. لكن ts-patch لا يقوم بتثبيت TypeScript بنفسه - فهو يفترض أنك قمت بإضافته بالفعل. إذا لم يكن TypeScript موجودًا، يصدر npm ذلك التحذير.

لماذا هذا مهم لمشاريع TypeScript؟

TypeScript ليس مجرد لغة، بل هو نظام بيئي. العديد من الحزم (مثل @types/react، ts-loader، eslint-plugin-typescript) تعمل فوق TypeScript. إذا كان لديك إصدار TypeScript 5.0 مثبتًا، والحزمة تتطلب 4.0+، فكل شيء على ما يرام. ولكن إذا لم يكن TypeScript موجودًا على الإطلاق، تبدأ المشاكل.

هذا مثال واقعي من الحياة. لنفترض أنك تكتب سكريبتًا صغيرًا بلغة TypeScript وتستخدم ts-patch لتحويل الكود. تقوم بتشغيل:

npm install ts-patch --save-dev

وتحصل على:

npm WARN ts-patch@3.2.1 requires a peer of typescript@>=4.0 but none is installed.\nYou must install peer dependencies yourself.

ماذا تفعل؟ هل تذعر؟ لا. فقط قم بتثبيت TypeScript:

npm install typescript --save-dev

تم حل المشكلة. ولكن ماذا لو كان لديك بالفعل TypeScript، ولكن بإصدار مختلف؟ هنا يبدأ الجزء المثير للاهتمام.

مقارنة الأساليب: كيفية تثبيت التبعيات النظيرة

هناك عدة طرق للتعامل مع هذا الخطأ. دعنا نقارنها بمثال مشروع TypeScript.

الطريقة 1: التثبيت اليدوي (الكلاسيكية)

أبسط وأضمن طريقة هي قراءة التحذير وتثبيت الحزمة المطلوبة يدويًا. ترى أن typescript@>=4.0 مطلوب، وتقوم بإضافته:

npm install typescript@^4.0 --save-dev

الإيجابيات:

\n
• تحكم كامل في الإصدار.
\n
• لا توجد مفاجآت مخفية.
\n

السلبيات:

\n
• تحتاج إلى قراءة رسائل npm بعناية.
\n
• إذا كان هناك العديد من الحزم، تصبح العملية روتينية.
\n

هذه الطريقة مثالية للمشاريع الصغيرة حيث تعرف بالضبط التبعيات التي تحتاجها.

الطريقة 2: التثبيت التلقائي باستخدام npx أو الإضافات

بعض الأدوات، مثل npm-check أو install-peerdeps، يمكنها تثبيت جميع التبعيات النظيرة تلقائيًا لحزمة معينة. قم بتثبيت الأداة بشكل عام:

npm install -g install-peerdeps