npm 6.4

package.json




npm

تفاصيل التعامل مع package.json npm.

وصف

هذه الوثيقة هي كل ما تحتاج إلى معرفته حول ما هو مطلوب في ملف package.json الخاص بك. يجب أن يكون JSON الفعلي ، وليس مجرد كائن حرفي لـ JavaScript.

يتأثر الكثير من السلوك الموضح في هذا المستند بإعدادات التكوين الموضحة في npm-config .

اسم

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

الاسم هو ما يسمى الشيء الخاص بك.

بعض القواعد:

  • يجب أن يكون الاسم أقل من 214 حرفًا. يتضمن ذلك نطاق حزم النطاق.
  • لا يمكن أن يبدأ الاسم بنقطة أو شرطة سفلية.
  • يجب ألا تحتوي الحزم الجديدة على أحرف كبيرة في الاسم.
  • ينتهي الاسم بكونه جزءًا من عنوان URL ، وسيطة في سطر الأوامر ، واسم مجلد. لذلك ، لا يمكن أن يحتوي الاسم على أي أحرف غير آمنة لعنوان URL.

بعض النصائح:

  • لا تستخدم نفس الاسم كوحدة أساسية للعقدة.
  • لا تضع "js" أو "عقدة" في الاسم. من المفترض أنه js ، لأنك تكتب ملف package.json ، ويمكنك تحديد المحرك باستخدام حقل "engines". (انظر أدناه.)
  • من المحتمل أن يتم تمرير الاسم كوسيطة تتطلب () ، لذا يجب أن يكون شيئًا قصيرًا ، ولكن أيضًا وصفًا معقولًا.
  • قد ترغب في التحقق من سجل npm لمعرفة ما إذا كان هناك شيء بهذا الاسم بالفعل ، قبل أن تلتصق به. https://www.npmjs.com/

يمكن أن يكون اسمًا مسبوقًا من قبل نطاق ، على سبيل المثال @myorg/mypackage . انظر npm-scope لمزيد من التفاصيل.

الإصدار

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

يجب أن يكون الإصدار node-semver بواسطة node-semver ، والتي يتم المجمعة مع npm كـ تبعية. ( npm install semver لاستخدامه بنفسك.)

المزيد عن أرقام الإصدارات semver في semver .

وصف

ضع وصفا فيه. إنها سلسلة. يساعد ذلك الأشخاص في اكتشاف الحزمة ، حيث إنها مدرجة في npm search .

الكلمات الدالة

ضع الكلمات الرئيسية فيه. انها مجموعة من الاوتار. يساعد ذلك الأشخاص في اكتشاف الحزمة الخاصة بك كما هي مدرجة في npm search .

الصفحة الرئيسية

عنوان url إلى الصفحة الرئيسية للمشروع.

مثال:

"homepage": "https://github.com/owner/project#readme"

البق

عنوان url الخاص بمتتبع المشكلة في مشروعك و / أو عنوان البريد الإلكتروني الذي يجب الإبلاغ عن المشكلات فيه. هذه هي مفيدة للأشخاص الذين يواجهون مشاكل مع الحزمة الخاصة بك.

يجب أن تبدو هذه:

{ "url" : "https://github.com/owner/project/issues"
, "email" : "[email protected]"
}

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

إذا تم توفير عنوان url ، فسيتم استخدامه بواسطة الأمر npm bugs .

رخصة

يجب عليك تحديد ترخيص لحزمك حتى يعرف الناس كيف يُسمح لهم باستخدامه ، وأي قيود تفرضه عليه.

إذا كنت تستخدم ترخيصًا شائعًا مثل BSD-2-Clause أو MIT ، فأضف معرّف ترخيص SPDX الحالي للترخيص الذي تستخدمه ، على النحو التالي:

{ "license" : "BSD-3-Clause" }

يمكنك التحقق من القائمة الكاملة لمعرفات ترخيص SPDX . من الناحية المثالية ، يجب اختيار واحد معتمد من OSI .

إذا كانت رزمتك مرخصة بموجب تراخيص متعددة مشتركة ، فاستخدم سلسلة SPDX لتركيب تعبير إصدار الترخيص 2.0 ، كما يلي:

{ "license" : "(ISC OR GPL-3.0)" }

إذا كنت تستخدم ترخيصًا لم يتم تعيين معرف SPDX له ، أو إذا كنت تستخدم ترخيصًا مخصصًا ، فاستخدم قيمة سلسلة مثل هذه:

{ "license" : "SEE LICENSE IN <filename>" }

ثم قم بتضمين ملف باسم <filename> في المستوى العلوي للحزمة.

تستخدم بعض الحزم القديمة كائنات ترخيص أو خاصية "تراخيص" تحتوي على مصفوفة من كائنات الترخيص:

// Not valid metadata
{ "license" :
  { "type" : "ISC"
  , "url" : "https://opensource.org/licenses/ISC"
  }
}

// Not valid metadata
{ "licenses" :
  [
    { "type": "MIT"
    , "url": "https://www.opensource.org/licenses/mit-license.php"
    }
  , { "type": "Apache-2.0"
    , "url": "https://opensource.org/licenses/apache2.0.php"
    }
  ]
}

هذه الأنماط متوقفة الآن. بدلاً من ذلك ، استخدم تعبيرات SPDX ، مثل هذا:

{ "license": "ISC" }

{ "license": "(MIT OR Apache-2.0)" }

أخيرًا ، إذا كنت لا ترغب في منح الآخرين الحق في استخدام حزمة خاصة أو غير منشورة تحت أي شروط:

{ "license": "UNLICENSED" }

فكر أيضًا في إعداد "private": true لمنع النشر غير المقصود.

حقول الأشخاص: المؤلف والمساهمين

"المؤلف" هو شخص واحد. "المساهمين" هو مجموعة من الناس. "الشخص" هو كائن به حقل "اسم" و "url" و "email" اختياريًا ، على النحو التالي:

{ "name" : "Barney Rubble"
, "email" : "[email protected]"
, "url" : "http://barnyrubble.tumblr.com/"
}

أو يمكنك تقصير كل ذلك في سلسلة واحدة ، وسوف تقوم npm بتحليلها لك:

"Barney Rubble <[email protected]> (http://barnyrubble.tumblr.com/)"

كل من البريد الإلكتروني وعنوان url اختياريان في كلتا الحالتين.

يحدد npm أيضًا حقل "مشرفين" من المستوى الأعلى بمعلومات مستخدم npm.

ملفات

حقل files الاختيارية هو مصفوفة من أنماط الملفات التي تصف الإدخالات التي سيتم تضمينها عند تثبيت الحزمة الخاصة بك كاعتمادية. تتبع أنماط الملفات بنية مشابهة لـ .gitignore ، ولكن يتم عكسها: بما في ذلك نمط ملف أو دليل أو نمط glob ( * ، **/* ، وما إلى ذلك) سيجعله بحيث يتم تضمين الملف في tarball عندما تكون معبأة. يؤدي حذف هذا الحقل إلى جعله افتراضيًا ["*"] ، مما يعني أنه سيتضمن جميع الملفات.

يتم أيضًا تضمين أو استثناء بعض الملفات والدلائل الخاصة بغض النظر عما إذا كانت موجودة في مصفوفة files (انظر أدناه).

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

لا يمكن استبعاد الملفات المتضمنة في حقل "package.json # files" من خلال .npmignore أو .npmignore .

يتم دائمًا تضمين ملفات معينة ، بغض النظر عن الإعدادات:

  • package.json
  • README
  • CHANGES / CHANGELOG / HISTORY
  • LICENSE / LICENCE
  • NOTICE
  • الملف في الحقل "الرئيسي"

يمكن أن يكون لأي من README و CHANGES و LICENSE & NOTICE أي حالة وامتداد.

على العكس ، يتم تجاهل بعض الملفات دائمًا:

  • .git
  • CVS
  • .svn
  • .hg
  • .lock-wscript
  • .wafpickle-N
  • .*.swp
  • .DS_Store
  • ._*
  • npm-debug.log
  • .npmrc
  • node_modules
  • config.gypi
  • *.orig
  • package-lock.json (استخدم shrinkwrap بدلاً من ذلك)

الأساسية

الحقل الرئيسي هو معرف الوحدة النمطية وهو نقطة الإدخال الأساسية إلى البرنامج. بمعنى ، إذا تم تسمية الحزمة الخاصة بك foo ، وقام مستخدم بتثبيتها ، ثم require("foo") ، فسيتم إرجاع كائن صادرات الوحدة الرئيسية الخاصة بك.

يجب أن يكون هذا معرّف وحدة نمطية نسبة إلى جذر مجلد الحزمة.

بالنسبة لمعظم الوحدات ، يكون من المنطقي أن يكون لديك نص رئيسي ، وكثيرًا ما لا يكون كثيرًا.

المتصفح

إذا كان الغرض من وحدتك هو استخدام جانب العميل ، فيجب استخدام حقل المستعرض بدلاً من الحقل الرئيسي. هذا مفيد لتلميح المستخدمين أنه قد يعتمد على الأوليات التي لا تتوفر في الوحدات النمطية Node.js. (على سبيل المثال window )

بن

تحتوي الكثير من الحزم على ملف تنفيذي واحد أو أكثر ترغب في تثبيته في PATH. يجعل npm هذا سهل جدا (في الحقيقة ، هو يستعمل هذه الميزة لتثبيت "npm" قابل للتنفيذ.)

لاستخدام هذا ، قم بتزويد حقل bin في package.json الخاص بك وهو عبارة عن خريطة لاسم الأمر لاسم الملف المحلي. عند التثبيت ، سيعمل npm على ترميز هذا الملف إلى prefix/bin لعمليات التثبيت العامة أو ./node_modules/.bin/ لعمليات التثبيت المحلية.

على سبيل المثال ، يمكن أن يكون myapp هذا:

{ "bin" : { "myapp" : "./cli.js" } }

لذلك ، عند تثبيت myapp ، فسوف ينشئ cli.js البرنامج النصي cli.js إلى /usr/local/bin/myapp .

إذا كان لديك ملفًا قابلاً للتنفيذ ، ويجب أن يكون اسمه هو اسم الحزمة ، فيمكنك فقط توفيره كسلسلة. فمثلا:

{ "name": "my-program"
, "version": "1.2.5"
, "bin": "./path/to/program" }

سيكون نفس هذا:

{ "name": "my-program"
, "version": "1.2.5"
, "bin" : { "my-program" : "./path/to/program" } }

الرجاء التأكد من أن الملف (الملفات) المشار إليها في bin يبدأ بـ #!/usr/bin/env node ، وإلا سيتم تشغيل البرامج النصية بدون العقدة القابلة للتنفيذ!

رجل

حدد إما ملفًا واحدًا أو مجموعة من أسماء الملفات لوضعها في برنامج man للعثور عليها.

إذا تم توفير ملف واحد فقط ، فسيتم تثبيته بحيث يكون ناتجًا عن man <pkgname> ، بغض النظر عن اسم الملف الفعلي الخاص به. فمثلا:

{ "name" : "foo"
, "version" : "1.2.3"
, "description" : "A packaged foo fooer for fooing foos"
, "main" : "foo.js"
, "man" : "./man/doc.1"
}

من شأنه أن يربط ملف ./man/doc.1 في مثل هذا الهدف man foo

إذا لم يبدأ اسم الملف باسم الحزمة ، فسيتم البدء فيه مسبقًا. إذا هذا:

{ "name" : "foo"
, "version" : "1.2.3"
, "description" : "A packaged foo fooer for fooing foos"
, "main" : "foo.js"
, "man" : [ "./man/foo.1", "./man/bar.1" ]
}

سوف إنشاء ملفات للقيام man foo man foo-bar .

يجب أن تنتهي الملفات .gz برقم ، واختيارياً .gz لاحقة إذا كانت مضغوطة. يحدد الرقم الذي يتم تثبيت مقطع الرجل في الملف عليه.

{ "name" : "foo"
, "version" : "1.2.3"
, "description" : "A packaged foo fooer for fooing foos"
, "main" : "foo.js"
, "man" : [ "./man/foo.1", "./man/foo.2" ]
}

سوف إنشاء إدخالات man foo man 2 foo

الدلائل

تفاصيل مواصفات Packages CommonJS بضع طرق يمكنك الإشارة إلى بنية الحزمة الخاصة بك باستخدام كائن directories . إذا نظرت إلى حزمة npm's package.json ، سترى أنه يحتوي على أدلة لـ doc و lib و man.

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

directories.lib

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

directories.bin

إذا قمت بتحديد دليل bin في directories.bin ، فستتم إضافة كافة الملفات الموجودة في هذا المجلد.

وبسبب الطريقة التي يعمل بها التوجيه bin ، فإن تحديد مسار bin وإعداد directories.bin هو خطأ. إذا كنت تريد تحديد ملفات فردية ، استخدم bin ، ولجميع الملفات الموجودة في مجلد bin موجود ، استخدم directories.bin .

directories.man

مجلد مليء بصفحات man. سكر لتوليد مجموعة "رجل" عن طريق المشي المجلد.

directories.doc

ضع ملفات تخفيض السعر هنا. في نهاية المطاف ، سيتم عرض هذه بشكل لطيف ، ربما ، في يوم من الأيام.

directories.example

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

directories.test

ضع اختباراتك هنا. لا يتعرض حاليًا ، ولكنه قد يكون في المستقبل.

مستودع

حدد المكان الذي توجد فيه شفرتك. هذا مفيد للأشخاص الذين يرغبون في المساهمة. إذا كان git repo npm docs على GitHub ، npm docs الأمر من العثور على npm docs .

افعلها هكذا:

"repository" :
  { "type" : "git"
  , "url" : "https://github.com/npm/npm.git"
  }

"repository" :
  { "type" : "svn"
  , "url" : "https://v8.googlecode.com/svn/trunk/"
  }

يجب أن يكون عنوان URL هو عنوان url متاحًا بشكل عام (ربما للقراءة فقط) والذي يمكن تسليمه مباشرةً إلى برنامج VCS دون أي تعديل. لا ينبغي أن يكون رابطًا إلى صفحة مشروع html تضعها في متصفحك. انها لأجهزة الكمبيوتر.

بالنسبة إلى GitHub أو GitHub gist أو Bitbucket أو مستودعات GitLab ، يمكنك استخدام نفس صيغة الاختصار التي تستخدمها npm install :

"repository": "npm/npm"

"repository": "github:user/repo"

"repository": "gist:11081aaa281"

"repository": "bitbucket:user/repo"

"repository": "gitlab:user/repo"

مخطوطات

الخاصية "scripts" هي قاموس يحتوي على أوامر البرنامج النصي التي يتم تشغيلها في أوقات مختلفة في دورة حياة الحزمة الخاصة بك. المفتاح هو حدث دورة الحياة ، والقيمة هي الأمر الذي سيتم تشغيله عند هذه النقطة.

راجع npm-scripts لمعرفة المزيد حول كتابة برامج النصوص النصية.

التكوين

يمكن استخدام كائن "التكوين" لتعيين معلمات التكوين المستخدمة في البرامج النصية الحزمة التي تستمر عبر الترقيات. على سبيل المثال ، إذا كانت الحزمة تحتوي على ما يلي:

{ "name" : "foo"
, "config" : { "port" : "8080" } }

ثم كان هناك أمر "start" الذي قام بعد ذلك بالرجوع إلى متغير بيئة npm_package_config_port ، ثم يمكن للمستخدم تجاوز ذلك عن طريق القيام npm config set foo:port 8001 .

راجع npm-config و npm-scripts لمعرفة المزيد عن npm-scripts الحزم.

تبعيات

يتم تحديد التبعيات في كائن بسيط يقوم بتعيين اسم حزمة إلى نطاق إصدار. نطاق الإصدار عبارة عن سلسلة تحتوي على واحد أو أكثر من الواصفات المنفصلة في الفضاء. يمكن أيضًا تحديد التبعيات باستخدام رابط تشريب أو عنوان URL.

من فضلك لا تضع أحزمة اختبار أو transpilers في كائن dependencies الخاصة بك. انظر devDependencies أدناه.

انظر semver للحصول على مزيد من التفاصيل حول تحديد نطاقات الإصدار.

  • version يجب أن تطابق version بالضبط
  • >version يجب أن يكون version أكبر من version
  • >=version الخ
  • <version
  • <=version
  • ~version " semver يعادل الإصدار" انظر semver
  • ^version "متوافق مع الإصدار" انظر semver
  • 1.2.x 1.2.0 و 1.2.1 وما إلى ذلك ، ولكن ليس 1.3.0
  • http://... راجع "عناوين URL كـ تبعيات" أدناه
  • * يتطابق مع أي إصدار
  • "" (سلسلة فارغة فقط)
  • version1 - version2 مثل >=version1 <=version2 .
  • range1 || range2 range1 || range2 إذا كان النطاق 1 أو النطاق 2 راضيًا.
  • git... راجع "Git URLs as dependendencies" أدناه
  • user/repo راجع "GitHub URLs" أدناه
  • tag إصدار محدد تم وضع علامة عليه ونشره كعلامة انظر npm-dist-tag
  • path/path/path انظر المسارات المحلية أدناه

على سبيل المثال ، هذه كلها صالحة:

{ "dependencies" :
  { "foo" : "1.0.0 - 2.9999.9999"
  , "bar" : ">=1.0.2 <2.1.2"
  , "baz" : ">1.0.2 <=2.3.4"
  , "boo" : "2.0.1"
  , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
  , "asd" : "http://asdf.com/asdf.tar.gz"
  , "til" : "~1.2"
  , "elf" : "~1.2.3"
  , "two" : "2.x"
  , "thr" : "3.3.x"
  , "lat" : "latest"
  , "dyl" : "file:../dyl"
  }
}

عناوين URL باعتبارها تبعيات

يمكنك تحديد عنوان URL للتنسبي بدلاً من نطاق الإصدار.

سيتم تنزيل وتثبيت هذا tarball محليًا على الحزمة الخاصة بك في وقت التثبيت.

Git URLs as dependendencies

Git urls هي من النموذج:

<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]

<protocol> هو واحد من git و git+ssh و git+http و git+https أو git+file .

إذا تم توفير #<commit-ish> ، فسيتم استخدامه لنسخ ذلك الالتزام بالضبط. إذا كان التزام الالتزام يحتوي على تنسيق #semver:<semver> ، <semver> يمكن أن يكون أي نطاق semver صالح أو إصدارًا دقيقًا ، وسيبحث npm عن أية علامات أو عمليات رفض تتطابق مع هذا النطاق في المستودع عن بُعد ، تمامًا كما هو الحال مع تبعية السجل. إذا لم يتم تحديد #<commit-ish> أو #semver:<semver> ، فسيتم استخدام #semver:<semver> master .

أمثلة:

git+ssh://[email protected]:npm/npm.git#v1.0.27
git+ssh://[email protected]:npm/npm#semver:^5.0
git+https://[email protected]/npm/npm.git
git://github.com/npm/npm.git#v1.0.27

GitHub URLs

اعتبارًا من الإصدار 1.1.65 ، يمكنك الرجوع إلى عناوين URL لـ GitHub كـ "foo": "user / foo-project". كما هو الحال مع عناوين URL git ، يمكن تضمين لاحقة commit-ish . فمثلا:

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "expressjs/express",
    "mocha": "mochajs/mocha#4727d357ea",
    "module": "user/repo#feature\/branch"
  }
}

المسارات المحلية

اعتبارًا من الإصدار 2.0.0 ، يمكنك توفير مسار إلى دليل محلي يحتوي على حزمة. يمكن حفظ المسارات المحلية باستخدام npm install -S أو npm install --save ، باستخدام أي من هذه النماذج:

../foo/bar
~/foo/bar
./foo/bar
/foo/bar

في هذه الحالة سيتم تطبيعهم إلى مسار نسبي وإضافته إلى package.json الخاصة بك. فمثلا:

{
  "name": "baz",
  "dependencies": {
    "bar": "file:../foo/bar"
  }
}

هذه الميزة مفيدة لتطوير دون اتصال محلي وإنشاء اختبارات تتطلب تثبيت npm في المكان الذي لا تريد فيه ضرب خادم خارجي ، ولكن لا يجب استخدامه عند نشر الحزم في السجل العام.

devDependencies

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

في هذه الحالة ، من الأفضل تعيين هذه العناصر الإضافية في كائن devDependencies .

سيتم تثبيت هذه الأشياء عند إجراء npm link أو npm install من جذر الحزمة ، ويمكن إدارتها مثل أي معلمة تكوين npm أخرى. راجع npm-config لمعرفة المزيد عن الموضوع.

بالنسبة إلى خطوات الإنشاء التي لا تكون خاصة بالنظام الأساسي ، مثل ترجمة CoffeeScript أو اللغات الأخرى إلى JavaScript ، استخدم البرنامج النصي prepare للقيام بذلك ، واجعل الحزمة المطلوبة devDependency.

فمثلا:

{ "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepare": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

سيتم تشغيل البرنامج النصي prepare قبل النشر ، بحيث يمكن للمستخدمين الاستفادة من الوظائف دون مطالبتهم بتجميعها بأنفسهم. في وضع dev (أي ، npm install محلي التشغيل) ، فإنه سيتم تشغيل هذا البرنامج النصي أيضًا ، بحيث يمكنك اختباره بسهولة.

peerDependencies

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

فمثلا:

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "tea": "2.x"
  }
}

وهذا يضمن أن حزمة tea-latte الخاصة بك يمكن تركيبها جنبا إلى جنب مع النسخة الرئيسية الثانية من tea الحزمة المضيفة فقط. يمكن أن يؤدي npm install tea-latte إلى الرسم البياني للاعتماد التالي:

├── [email protected]
└── [email protected]

ملاحظة: سيتم تثبيت الإصدارين 1 و 2 من peerDependencies تلقائيًا على peerDependencies إذا لم يتم peerDependencies بشكل صريح عند مستوى أعلى في شجرة التبعية. في الإصدار الرئيسي التالي من npm (npm @ 3) ، لن يكون هذا هو الحال. ستتلقى تحذيرًا أنه لم يتم تثبيت peerDependency بدلاً من ذلك. كان السلوك في npms 1 & 2 مربكًا في كثير من الأحيان ويمكن بسهولة وضعك في جحيم التبعية ، وهو موقف تم تصميم npm لتجنب أكبر قدر ممكن.

ستؤدي محاولة تثبيت مكون إضافي آخر بمتطلب متعارض إلى حدوث خطأ. لهذا السبب ، تأكد من أن متطلبات المكوِّن الإضافي واسعة قدر الإمكان ، وليس لتأمينها لإصدارات معينة من التصحيحات.

بافتراض أن المضيف يتطابق مع semver ، فإن التغييرات في النسخة الرئيسية لحزمة المضيف فقط ستكسر المكون الإضافي. وبالتالي ، إذا كنت قد عملت مع كل إصدار 1.x من حزمة المضيف ، فاستخدم "^1.0" أو "1.x" للتعبير عن هذا. إذا كنت تعتمد على الميزات المقدمة في 1.5.2 ، فاستخدم ">= 1.5.2 < 2" .

bundledDependencies

يحدد هذا مصفوفة من أسماء الحزم التي سيتم تجميعها عند نشر الحزمة.

في الحالات التي تحتاج فيها إلى حفظ حزم npm محليًا أو توفرها من خلال تنزيل ملف واحد ، يمكنك تجميع الحزم في ملف tarball بتحديد أسماء الحزم في مصفوفة npm pack وتنفيذ npm pack .

فمثلا:

إذا حددنا حزمة package.json مثل هذا:

{
  "name": "awesome-web-framework",
  "version": "1.0.0",
  "bundledDependencies": [
    "renderized", "super-streams"
  ]
}

يمكننا الحصول awesome-web-framework-1.0.0.tgz عن طريق تشغيل npm pack . يحتوي هذا الملف على التبعيات renderized والمجموعات super-streams التي يمكن تثبيتها في مشروع جديد عن طريق تنفيذ npm install awesome-web-framework-1.0.0.tgz .

إذا تم كتابة هذا "bundleDependencies" مكتوبة ، فإن ذلك يتم تكريمه أيضًا.

optionalDependencies

إذا كان بالإمكان استخدام التبعية ، لكنك ترغب في أن تستمر npm إذا لم يكن من الممكن العثور عليها أو فشل في تثبيتها ، فيمكنك وضعها في كائن Dependencies optionalDependencies . هذه خريطة لاسم الحزمة إلى الإصدار أو عنوان url ، تمامًا مثل كائن dependencies . الفرق هو أن فشل الإنشاء لا يؤدي إلى فشل التثبيت.

لا يزال لديك مسؤولية البرنامج للتعامل مع عدم التبعية. على سبيل المثال ، شيء من هذا القبيل:

try {
  var foo = require('foo')
  var fooVersion = require('foo/package.json').version
} catch (er) {
  foo = null
}
if ( notGoodFooVersion(fooVersion) ) {
  foo = null
}

// .. then later in your program ..

if (foo) {
  foo.doFooThings()
}

ستتجاوز الإدخالات في Dependencies optionalDependencies إدخالات نفس الاسم في dependencies ، لذلك عادةً ما يكون من الأفضل وضعه في مكان واحد فقط.

محركات

يمكنك تحديد إصدار العقدة التي تعمل عليها الأشياء الخاصة بك:

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

وكما هو الحال مع التبعيات ، إذا لم تحدد الإصدار (أو إذا حددت "*" كإصدار) ، فستقوم أي نسخة من العقدة.

إذا حددت حقل "محركات" ، فستتطلب npm أن تكون "عقدة" في مكان ما في هذه القائمة. إذا تم حذف "المحركات" ، فستفترض npm فقط أنها تعمل على العقدة.

يمكنك أيضًا استخدام حقل "المحركات" لتحديد إصدارات npm التي تستطيع تثبيت البرنامج بشكل صحيح. فمثلا:

{ "engines" : { "npm" : "~1.0.20" } }

ما لم يقم المستخدم بتعيين إشارة التكوين المشغلة engine-strict ، يكون هذا الحقل استشاريًا فقط وسيقوم فقط بإصدار تحذيرات عند تثبيت الحزمة الخاصة بك كاعتمادية.

engineStrict

تمت إزالة هذه الميزة في npm 3.0.0

قبل استخدام npm 3.0.0 ، تم استخدام هذه الميزة لمعالجة هذه الحزمة كما لو كان المستخدم قد قام بتثبيت engine-strict . لم تعد مستخدمة.

عظم

يمكنك تحديد أنظمة التشغيل التي سيتم تشغيل الوحدة الخاصة بك عليها:

"os" : [ "darwin", "linux" ]

يمكنك أيضًا وضع قائمة سوداء بدلاً من أنظمة التشغيل القائمة على القائمة البيضاء ، فقط قم بإدراج نظام القائمة السوداء مع "!":

"os" : [ "!win32" ]

يتم تحديد نظام التشغيل المضيف من خلال process.platform

يتم السماح لكل من القائمة السوداء ، والقائمة البيضاء ، على الرغم من عدم وجود أي سبب وجيه للقيام بذلك.

وحدة المعالجة المركزية

إذا تم تشغيل التعليمات البرمجية الخاصة بك فقط على أبنية cpu معينة ، يمكنك تحديد أي منها.

"cpu" : [ "x64", "ia32" ]

مثل خيار os ، يمكنك أيضًا إنشاء قائمة سوداء للهندسة المعمارية:

"cpu" : [ "!arm", "!mips" ]

يتم تحديد بنية المضيف بواسطة process.arch

preferGlobal

إهمال

يستخدم هذا الخيار لتحذير npm ، ولكنه لن يحذر بعد الآن. هو محض هناك لأغراض إعلامية. من المستحسن الآن تثبيت أي ثنائيات مثل devDependencies المحلي كلما كان ذلك ممكنا.

نشر

إذا عينت "private": true في الحزمة package.json ، فسترفض npm نشرها.

هذه طريقة لمنع النشر العرضي للمستودعات الخاصة. إذا كنت ترغب في التأكد من نشر حزمة معينة على سجل محدد فقط (على سبيل المثال ، التسجيل الداخلي) ، publishConfig قاموس publishConfig الموضح أدناه لتجاوز حد registry في قائمة publishConfig registry .

publishConfig

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

يمكن إلغاء أي من قيم التهيئة ، ولكن بالطبع ، لا يهم سوى "tag" و "registry" و "access" لأغراض النشر.

راجع npm-config للاطلاع على قائمة خيارات التكوين التي يمكن استبدالها.

قيم افتراضية

ستقوم npm بتحديد بعض القيم استنادًا إلى محتويات الحزمة.

  • "scripts": {"start": "node server.js"}

    إذا كان هناك ملف server.js في جذر الحزمة الخاصة بك ، فسيقوم npm افتراضيًا start الأمر start إلى node server.js .

  • "scripts":{"install": "node-gyp rebuild"}

    إذا كان هناك ملف binding.gyp في جذر الحزمة ولم تقم بتعريف install أو نص برمجي preinstall ، فسيقوم npm افتراضيًا install أمر install باستخدام العقدة gyp.

  • "contributors": [...]

    إذا كان هناك ملف AUTHORS في جذر الحزمة ، فستتعامل npm مع كل سطر على هيئة Name <email> (url) ، حيث يكون البريد الإلكتروني وعنوان url اختياريين. سيتم تجاهل الأسطر التي تبدأ بـ # أو تكون فارغة.

أنظر أيضا