Uncategorized

الدليل إلى package.json

كتب بواسطة: 07/11/2019 لا يوجد تعليقات

ملف package.json هو عنصر أساسي في الكثير من التطبيقات التي يعتمد الكود فيها على بيئة node.js.

إذا كنت عملت من قبل في JavaScript، أو تعاملت مع مشروع JavaScript أو Node.js، أو فمت بعمل مشروع front-end، فبالتأكيد ستكون قابلت ملف package.json.

لماذا يتواجد هذا الملف؟ ما الذي يجب أن تعرفه، وما هي بعض الأشياء الرائعة التي يمكنك القيام بها؟

ملف package.json هو نوع من الوثيقة الأساسية (manifest)  في مشروعك. يمكن أن تفعل الكثير من الأشياء التي ليس لها علاقة ببعضها البعض مطلقا. إنه مستودع مركزي لتهيئة الأدوات. على سبيل المثال، هي المكان لتخزين أسماء وإصدارات مكتبات npm  و yarn التي تم بتركيبها.

  • هيكلية الملف
  • خصائص الانهيار
    • الاسم
    • المؤلف
    • المساهمون
    • الأخطاء (bugs)
    • الصفحة الرئيسية
    • الاصدار
    • الرخصة
    • الكلمات الدلالية
    • الوصف
    • المستودع
    • الرئيسي
    • خاص
    • نصوص أكواد (scripts)
    • التبعيات (dependencies)
    • تبعيات التطوير (devDependencies)
    • المحركات
    • قائمة المتصفح (browserslist)
    • لوحة الأوامر – خصائص محددة
  • إصدارات الحزمة

هيكلية الملف

هنا مثال على ملف package.json:

إنه فارغ! لا توجد متطلبات ثابتة لما يجب أن يكون في ملف Package.json، لتطبيق ما. الشرط الوحيد هو أن يكون على تنسيق JSON، وإلا لا يمكن قراءته من قبل البرامج التي تحاول الوصول إلى خصائصه برمجياً.

إذا كنت تقوم ببناء حزمة Node.js التي تريد توزيعها على npm،  فإن الأمور تتغير بشكل جذري، ويجب أن يكون لديك مجموعة من الخصائص التي ستساعد الآخرين على استخدامها. سنعرف المزيد عن هذا لاحقاً.

هذا ملف package.json آخر: 

إنه يعرِّف خاصية الاسم (name) التي تخبر عن اسم التطبيق أو الحزمة الموجودة في نفس المجلد الذي فيه هذا الملف.

هنا مثال أكثر تعقيداً والذي استخرجته من مشروع Vue.js:

هناك الكثير من الأشياء التي تحدث هنا:

  • الاسم (name) يحدد اسم التطبيق/ الحزمة
  • الاصدار (version) يشير إلى إصدار النسخة الحالية
  • الوصف (description) وصف مختصر للتطبيق / الحزمة
  • الرئيسي (main) يحدد نقطة دخول التطبيق
  • خاص (private) لو تم تعيينه على صحيح (true) يمنع نشر التطبيق/ الحزمة عن طريق الخطأ على npm
  • نصوص الكود (scripts) تعرّف مجموعة من نصوص العقد (node scripts)  التي يمكنك تشغيلها
  • التبعيات ( dependencies) يحدد قائمة الحزمة التي تم تحميلها من npm كتبعيات
  • تبعيات التطوير (devDependencies) يحدد قائمة الحزمة التي تم تحميلها من npm كتبعيات تطوير 
  • المحركات (engines) يحدد أي إصدار من Node يعمل معه التطبيق/ الحزمة
  • قائمة المتصفح (browserslist) يحدد أي متصفح ( مع إصداره) يجب أن يتم دعمه

كل هذه الخصائص تستخدم إما عن طريق npm أو عن طريق أدوات أخرى يمكن استخدامها.

خصائص الانهيار

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

معظم هذه الخصائص لا تستخدم إلا على https://www.npmjs.com/ ، أو بواسطة نصوص (scripts) تتفاعل مع كود خاصة بـ npm  أو غيره.

الاسم (name)

يحدد اسم الحزمة.

مثال: 

يجب أن يكون الاسم أقل من 214 حرفاً، وأن لا يحتوي على مسافات، يمكن أن يحتوي فقط على حروف صغيرة، واصلات (-) أو شرطات سفلية (_).

وذلك لأنه عندما يتم نشر حزمة على اnpm، تحصل على عنوان URL الخاص بها بناءً على هذه الخاصية.

إذا قمت بنشر هذه الحزمة علانية على GitHub، فإن القيمة الجيدة لهذه الخاصية هي اسم مستودع GitHub.

المؤلف (author)

يحدد قائمة مؤلفين الحزمة.

مثال:

يمكن استخدامه أيضاً بهذا التنسيق:

المساهمين (contributors)

بالإضافة إلى المؤلف يمكن أن يحتوي المشروع على واحد أو أكثر من المساهمين. هذه الخاصية مصفوفة تسرد أسماءهم.

مثال:

ويمكن استخدام هذا التنسيق أيضاً:

الأخطاء (bugs)

روابط لمشاكل الحزمة التي تم تتبعها، تشبه إلى حد كبير صفحة المشاكل في GitHub.

مثال:

الصفحة الرئيسية (homepage)

تحدد الصفحة الرئيسية للحزمة.

مثال:

الإصدار (version)

يشير إلى الإصدار الحالي للحزمة.

مثال:

تتبع هذه الخاصية تنسيق (semver) للإصدارات، مما يعني أن النسخة يتم التعبير عنها دائماً بثلاثة أرقام: x.x.x

الرقم الأول هو الإصدار الرئيسي، والثاني هو الإصدار الثانوي والثالث هو إصدار التصحيح.

هناك معنى في هذه الأرقام: إصدار يعمل على إصلاح الأخطاء فقط هو إصدار تصحيح، إصدار يقدم تغييرات متفق عليها هو إصدار ثانوي، الإصدار الرئيسي يمكن أن يكون له تغييرات فاصلة.

الرخصة (license)

تشير إلى رخصة الحزمة.

مثال:

الكلمات الدلالية (keywords)

تحتوي هذه الخاصية على مجموعة من الكلمات المفتاحية التي ترتبط بما تقوم به حزمتك.

مثال:

يساعد ذلك الناس على العثور على حزمتك عند تصفح حزم مماثلة، أو عند تصفح موقع https://www.npmjs.com/.

الوصف (description) 

تحتوي هذه الخاصية على وصف مختصر للحزمة.

مثال:

وهذا مفيد بشكل خاص إذا قررت نشر حزمتك  على npm حتى يتمكن الناس من معرفة ماهية الحزمة.

المستودع (repository) 

تحدد هذه الخاصية مكان مستودع الحزمة هذا.

مثال:

لاحظ بادئة github. وهناك خدمات مشهورة أخرى  في الحزمة:

يمكنك تعيين نظام التحكم بالإصدار بشكل صريح:

الرئيسية (main)

يحدد نقطة دخول الحزمة.

عندما تقوم باستيراد هذه الحزمة في تطبيق ما، هذا هو المكان الذي سيبحث فيه التطبيق عن وحدة التصدير.

مثال:

الخاص (private)

لو تم تعيينه على صحيح (true) يمنع نشر التطبيق/ الحزمة عن طريق الخطأ على npm.

مثال:

نصوص الكود (scripts)

 تعرّف مجموعة من نصوص العقد (node scripts)  التي يمكنك تشغيلها.

مثال:

نص الكود هذا عبارة عن سطر أوامر في التطبيقات. تستطيع تشغيلهم عن طريق استدعاء npm run XXXX أو yarn XXXX، بينما XXXX هو اسم  الأمر، على سبيل المثال: npm run dev.

تستطيع كتابة أي اسم تريده للأمر، ونص الكود حرفياً يستطيع عمل أي شيء تريده.

التبعيات (dependencies)

يحدد قائمة الحزمة التي تم تحميلها من npm كتبعيات.

عندما تقوم بتحميل الحزمة عن طريق npm أو yarn:

هذه الحزمة سوف يتم إدراجها أوتوماتيكياً في هذه القائمة.

مثال:

تبعيات التطوير (devDependencies)

 يحدد قائمة الحزمة التي تم تحميلها من npm كتبعيات تطوير .

تختلف عن التبعيات (dependencies)، لأنه من المفترض أن يتم تركيبها فقط على آلة تطوير، وليس من الضروري أن يتم تشغيل الكود في الإنتاج.

عندما تقوم بتحميل الحزمة باستخدام npm أو yarn:

هذه الحزمة تم إدراجها أوتوماتيكياُ في هذه القائمة.

مثال:

المحركات (engines)

 يحدد أي إصدار من Node يعمل معه التطبيق/ الحزمة.

مثال:

قائمة المتصفح (browserslist)

 يحدد أي متصفح ( مع إصداره) يجب أن يتم دعمه. تمت الإشارة إليها من قبل Balabel، Autoprefixer، وأدوات أخرى، لإضافة polyfills (التعبئات) و fallbacks (الخطط البديلة) اللازمة للمتصفحات التي تستهدفها فقط.

مثال:

تعني هذه التهيئة أنك تريد دعم آخر إصدارين رئيسيين من جميع المتصفحات باستخدام 1٪ على الأقل من الاستخدام (من إحصائيات CanIUse.com) باستثناء متصفح IE8 والأدنى.

(راجع المزيد)

لوحة الأوامر – خصائص محددة

يمكن أن يستضيف ملف package.json أيضًا تهيئة خاصة بالأوامر، على سبيل المثال Babel و ESLint والمزيد.

لكل منها خاصية محددة، مثل eslintConfig، و babel وغيرها. هذه أوامر خاصة، ويمكنك العثور على كيفية إستخدام ذلك في وثائق الأوامر/المشروع الخاصة بكل منها.

إصدارات الحزمة

لقد رأيت في الوصف أعلاه أرقام الإصدار مثل هذه: ~3.0.0 أو^0.13.0. 

ماذا تعني، وأي من محددات الإصدار الأخرى يمكنك استخدامها؟

هذا الرمز يحدد أي تحديثات تقبلها الحزمة، من تلك التبعية.

نظراً لأن إستخدام semver (الإصدار الدلالي) لكل الإصدارات 3 خانات، أولها هو الإصدار الرئيسي، وثانيها الإصدار الثانوي والثالث هو إصدار التصحيح، فلديك هذه القواعد:

  • ~: لو كتبت ~0.13.0، تريد فقط تحديث إصدارات التصحيح: الرقم هذا 0.13.1 جيد، لكن 0.14.0 ليس جيداً.
  • ^: لو كتبت ^0.13.0، تريد تحديث إصدارات التصحيح والاصدارات الثانوية: 0.13.1،  0.14.0 وهكذا. 
  • *: لو كتبت * ، هذا يعني أنك تقبل بكل التحديثات، بما فيها التحديثات الثانوية والرئيسية.
  • >: أنت تقبل بأي إصدار أكبر من الإصدار المحدد. 
  • >=: أنت تقبل بأي إصدار أكبر أو يساوي  الإصدار المحدد.
  • <=: أنت تقبل بأي إصدار أقل أو يساوي الإصدار المحدد.
  • <: أنت تقبل بأي إصدار أقل من الإصدار المحدد. 

هناك قواعد أخرى أيضاً:

  • لا يوجد رمز: أنت تقبل الإصدار المحدد فقط.
  • Latest: تريد استخدام آخر إصدار متاح.

وتستطيع أن تدمج معظم الخصائص بالأعلى مثل: 1.0.0 || >=1.1.0 <1.2.0، إما لاستخدام الإصدار 1.0.0 أو إصدار واحد من 1.1.0 لأعلى، ولكن أقل من 1.2.0.

اترك تعليق