دليل package.json

يعد ملف package.json عنصرًا أساسيًا في الكثير من قواعد رموز التطبيقات استنادًا إلى النظام البيئي Node.js.

إذا كنت تعمل باستخدام JavaScript ، أو سبق لك التفاعل مع مشروع JavaScript أو Node.js أو مشروع الواجهة الأمامية ، فأنت بالتأكيد قابلتpackage.jsonملف.

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

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

هيكل الملف

فيما يلي مثال لملف package.json:

{

}

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

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

هذه حزمة أخرى. json:

{
  "name": "test-project"
}

يحدد أnameالخاصية ، التي تخبرنا باسم التطبيق أو الحزمة الموجودة في نفس المجلد حيث يوجد هذا الملف.

إليك مثال أكثر تعقيدًا ، استخرجته من عينة تطبيق Vue.js:

{
  "name": "test-project",
  "version": "1.0.0",
  "description": "A Vue.js project",
  "main": "src/main.js",
  "private": true,
  "scripts": {
    "dev": "webpack-dev-server --inline --progress --config build/webpack.dev.conf.js",
    "start": "npm run dev",
    "unit": "jest --config test/unit/jest.conf.js --coverage",
    "test": "npm run unit",
    "lint": "eslint --ext .js,.vue src test/unit",
    "build": "node build/build.js"
  },
  "dependencies": {
    "vue": "^2.5.2"
  },
  "devDependencies": {
    "autoprefixer": "^7.1.2",
    "babel-core": "^6.22.1",
    "babel-eslint": "^8.2.1",
    "babel-helper-vue-jsx-merge-props": "^2.0.3",
    "babel-jest": "^21.0.2",
    "babel-loader": "^7.1.1",
    "babel-plugin-dynamic-import-node": "^1.2.0",
    "babel-plugin-syntax-jsx": "^6.18.0",
    "babel-plugin-transform-es2015-modules-commonjs": "^6.26.0",
    "babel-plugin-transform-runtime": "^6.22.0",
    "babel-plugin-transform-vue-jsx": "^3.5.0",
    "babel-preset-env": "^1.3.2",
    "babel-preset-stage-2": "^6.22.0",
    "chalk": "^2.0.1",
    "copy-webpack-plugin": "^4.0.1",
    "css-loader": "^0.28.0",
    "eslint": "^4.15.0",
    "eslint-config-airbnb-base": "^11.3.0",
    "eslint-friendly-formatter": "^3.0.0",
    "eslint-import-resolver-webpack": "^0.8.3",
    "eslint-loader": "^1.7.1",
    "eslint-plugin-import": "^2.7.0",
    "eslint-plugin-vue": "^4.0.0",
    "extract-text-webpack-plugin": "^3.0.0",
    "file-loader": "^1.1.4",
    "friendly-errors-webpack-plugin": "^1.6.1",
    "html-webpack-plugin": "^2.30.1",
    "jest": "^22.0.4",
    "jest-serializer-vue": "^0.3.0",
    "node-notifier": "^5.1.2",
    "optimize-css-assets-webpack-plugin": "^3.2.0",
    "ora": "^1.2.0",
    "portfinder": "^1.0.13",
    "postcss-import": "^11.0.0",
    "postcss-loader": "^2.0.8",
    "postcss-url": "^7.2.1",
    "rimraf": "^2.6.0",
    "semver": "^5.3.0",
    "shelljs": "^0.7.6",
    "uglifyjs-webpack-plugin": "^1.1.1",
    "url-loader": "^0.5.8",
    "vue-jest": "^1.0.2",
    "vue-loader": "^13.3.0",
    "vue-style-loader": "^3.0.1",
    "vue-template-compiler": "^2.5.2",
    "webpack": "^3.6.0",
    "webpack-bundle-analyzer": "^2.9.0",
    "webpack-dev-server": "^2.9.1",
    "webpack-merge": "^4.1.0"
  },
  "engines": {
    "node": ">= 6.0.0",
    "npm": ">= 3.0.0"
  },
  "browserslist": [
    "> 1%",
    "last 2 versions",
    "not ie <= 8"
  ]
}

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

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

يتم استخدام كل هذه الخصائص من قبل أي منهماnpmأو غيرها من الأدوات التي يمكننا استخدامها.

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

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

يتم استخدام معظم هذه الخصائص فقط علىhttps://www.npmjs.com/، وغيرها من خلال البرامج النصية التي تتفاعل مع التعليمات البرمجية الخاصة بك ، مثلnpmاو اخرين.

name

يعيّن اسم الحزمة.

مثال:

"name": "test-project"

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

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

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

author

يسرد اسم مؤلف الحزمة

مثال:

{
  "author": "Flavio Copes <[email protected]> (https://flaviocopes.com)"
}

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

{
  "author": {
    "name": "Flavio Copes",
    "email": "[email protected]",
    "url": "https://flaviocopes.com"
  }
}

contributors

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

مثال:

{
  "contributors": [
    "Flavio Copes <[email protected]> (https://flaviocopes.com)"
  ]
}

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

{
  "contributors": [
    {
      "name": "Flavio Copes",
      "email": "[email protected]",
      "url": "https://flaviocopes.com"
    }
  ]
}

bugs

روابط لمتتبع مشكلة الحزمة ، على الأرجح صفحة مشكلات GitHub

مثال:

{
  "bugs": "https://github.com/flaviocopes/package/issues"
}

homepage

يضبط الصفحة الرئيسية للحزمة

مثال:

{
  "homepage": "https://flaviocopes.com/package"
}

version

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

مثال:

"version": "1.0.0"

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

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

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

license

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

مثال:

"license": "MIT"

keywords

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

مثال:

"keywords": [
  "email",
  "machine learning",
  "ai"
]

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

description

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

مثال:

"description": "A package to work with strings"

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

repository

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

مثال:

"repository": "github:flaviocopes/testing",

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

"repository": "gitlab:flaviocopes/testing",
"repository": "bitbucket:flaviocopes/testing",

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

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

يمكنك استخدام أنظمة مختلفة للتحكم في الإصدارات:

"repository": {
  "type": "svn",
  "url": "..."
}

main

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

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

مثال:

"main": "src/main.js"

private

إذا تم التعيين علىtrueيمنع التطبيق / الحزمة من النشر عن طريق الخطأnpm

مثال:

"private": true

scripts

يحدد مجموعة من البرامج النصية للعقد التي يمكنك تشغيلها

مثال:

"scripts": {
  "dev": "webpack-dev-server --inline --progress --config build/webpack.dev.conf.js",
  "start": "npm run dev",
  "unit": "jest --config test/unit/jest.conf.js --coverage",
  "test": "npm run unit",
  "lint": "eslint --ext .js,.vue src test/unit",
  "build": "node build/build.js"
}

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

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

dependencies

يعيّن قائمة بـnpmالحزم المثبتة على أنها تبعيات.

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

npm install <PACKAGENAME>
yarn add <PACKAGENAME>

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

مثال:

"dependencies": {
  "vue": "^2.5.2"
}

devDependencies

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

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

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

npm install --dev <PACKAGENAME>
yarn add --dev <PACKAGENAME>

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

مثال:

"devDependencies": {
  "autoprefixer": "^7.1.2",
  "babel-core": "^6.22.1"
}

engines

يضبط إصدارات Node.js والأوامر الأخرى التي تعمل عليها هذه الحزمة / التطبيق

مثال:

"engines": {
  "node": ">= 6.0.0",
  "npm": ">= 3.0.0",
  "yarn": "^0.13.0"
}

browserslist

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

مثال:

"browserslist": [
  "> 1%",
  "last 2 versions",
  "not ie <= 8"
]

يعني هذا التكوين أنك تريد دعم آخر نسختين رئيسيتين من جميع المتصفحات باستخدام 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.

تحميل مجانيكتيب Node.js


المزيد من دروس العقدة: