6 Августа 2018 JavaScript Перевод

Руководство по package.json

img

Файл package.json – основной элемент в больших приложениях, основанных на экосистеме Node.js.

Если вы работаете с JavaScript или когда-либо взаимодействовали с проектом JavaScript, Node.js, то вы наверняка встречали файл package.json.

Для чего он? Что вы должны знать о нем, и какие интересные вещи вы можете сделать с ним?

Файл package.json - это своего рода манифест для вашего проекта. Он может делать много вещей, совершенно не связанных друг с другом. Например, это центральный репозиторий конфигурации для инструментов. Также, npm и yarn хранят в нём названия и версии установленных пакетов.

Структура файла

Вот пример файла package.json:

{

}

Он пустой! Нет никаких жёстких требований к тому, что должно быть в файле package.json для приложения. Единственным требованием является то, что он должен соблюдать формат JSON, иначе не сможет быть прочитан программами, которые пытаются получить доступ к своим свойствам.

Если вы создаете пакет Node.js, который вы хотите распространять по npm, ситуация радикально меняется, и у вас должен быть набор свойств, которые помогут другим людям использовать его. Мы поговорим об этом позже.

А это другой package.json:

{
 "name": "test-project"
}

Он определяет свойство name, которое сообщает название приложения или пакета, которое содержится в той же папке что и файл package.json.

Вот более сложный пример, который я взял из приложения на 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 - определяет набор скриптов node, которые вы можете запустить
  • dependencies - определяет список пакетов npm, установленных как зависимости
  • devDependencies - определяет список пакетов npm, установленных как зависимости для разработки
  • engines - устанавливает, с какими версиями node этот пакет/приложение работает
  • browserslist - используется для определения, какие браузеры (и их версии) вы хотите поддерживать.

Все эти свойства считываются либо npm, либо другими инструментами, которые мы можем использовать.

Подробнее о свойствах

В этом разделе подробно описываются свойства, которые вы можете использовать. Я опишу свойства для пакетов, но то же самое относится и к локальным приложениям, которые вы не используете в качестве пакетов.

Большинство этих свойств используются только с https://www.npmjs.com.

NAME

Устанавливает название пакета.

Пример:

"name": "test-project"

Имя должно быть меньше 214 символов, в нём не должно быть пробелов, оно может содержать только строчные буквы, дефисы (-) или символ подчеркивания (_).

Это связано с тем, что, когда пакет опубликован в npm, он получает свой собственный URL, основанный на этом свойстве.

Если вы опубликовали этот пакет в GitHub, хорошим значением для этого свойства является имя репозитория GitHub.

AUTHOR

Устанавливает список авторов пакета.

Пример:

{
 "author": "Flavio Copes <flavio@flaviocopes.com> (https://flaviocopes.com)"
}

Также может быть в таком формате:

{
 "author": {
   "name": "Flavio Copes",
   "email": "flavio@flaviocopes.com",
   "url": "https://flaviocopes.com"
 }
}

CONTRIBUTORS

Как и в авторах, проект может иметь одного или нескольких участников. Это - массив, который их перечисляет.

Пример:

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

Также свойство может быть в таком формате:

{
 "contributors": [
   {
     "name": "Flavio Copes",
     "email": "flavio@flaviocopes.com",
     "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

Определяет набор node скриптов, которые можно запускать.

Пример:

"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 или yarn:

npm install <PACKAGENAME>
yarn add <PACKAGENAME>

этот пакет автоматически добавляется в этот список.

Пример:

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

DEVDEPENDENCIES

Указывает список пакетов npm, установленных как средства разработки.

Они отличаются от dependencies, потому что они предназначены для установки только на машине разработки, не требуемой для запуска кода в процессе производства.

Когда вы устанавливаете пакет с использованием npm или yarn:

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 и fallbacks, необходимые для тех браузеров, которые вы поддерживете.

Пример:

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

Эта конфигурация означает, что вы хотите поддерживать последние 2 основные версии всех браузеров с не менее чем 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.

Оригинал: THE PACKAGE.JSON GUIDE