Анатомия файла package.json

Development, Java | Amber | Комментировать запись

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

Запуск проекта

Самый простой и быстрый способ запустить проект с помощью менеджера пакетов npm – это использовать команду init и флаг -y, который отвечает yes на все вопросы системы:

$ npm init -y

Примечание: Название проекта будет таким же, как и название текущей папки, в которой вы находитесь.

Команда init запишет файл package.json в текущий каталог с кодом JSON, который выглядит следующим образом:

{
"name": "hello-alligator",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}

Давайте рассмотрим каждый ключ в исходном файле package.json:

• name: имя проекта, должно быть написано строчными буквами и подходить для URL. Имя может иметь префикс области видимости (например @angular/angular-cli). Если проект частный, имя проекта выбирать необязательно, но если проект будет опубликован, имя нужно обязательно, и оно должно быть уникальным в репозитории npm.
• version: номер версии, который должен быть понятен для node-semver. Это также необязательно для частных проектов, но обязательно и очень важно для публичных.
• description: описание проекта. Это опциональное поле. Оно полезно и помогает быстро найти проект в репозитории.
• main: входной файл проекта.
• scripts: ключ scripts ожидает объект с именами скриптов в качестве ключей и командами в качестве значений. Он нужен для указания сценариев, которые можно запускать непосредственно из командной строки и которые могут выполнять всевозможные задачи (запуск проекта на локальном сервере, сборка для производства или проведение тестов). Поле scripts – это то место, где вручную можно внести большинство изменений в типичный файл package.json.
• keywords: это массив, помогающий найти модуль в репозитории npm.
• author: это поле принимает объект с ключами name, email и url. Это позволяет людям легко связаться с автором проекта.
• license: принимает название лицензии с использованием идентификатора SPDX. По умолчанию применяется лицензия ISC, еще один популярный выбор – это MIT. Вы также можете использовать UNLICENSED для частных проектов и проектов с закрытым кодом.

Управление зависимостями

Основная сила npm – это возможность легко управлять зависимостями проекта. Поэтому вполне естественно, что файл package.json сосредоточен в основном на перечислении зависимостей. Существуют обычные зависимости, а также devDependencies, peerDependencies, optionalDependencies и bundledDependencies. Пройдемся по ним подробнее:

• dependencies: обычные зависимости проекта. Именно здесь, скорее всего, будет находиться основная часть ваших зависимостей. Добавить такие зависимости в свой проект можно с помощью $ npm install my-dependency.
• devDependencies: зависимости, которые нужны только при разработке проекта. Например, библиотеки тестирования и транспайлеры чаще всего следует добавлять как devDependencies. Добавить devDependency можно с помощью флага npm –save-dev с командой install.
• optionalDependencies: зависимости, которые npm должен рассматривать как опциональные. Если такие зависимости не установлены, npm не будет жаловаться или выдавать ошибку. Добавить опциональные зависимости можно с помощью –save-optional в команде install.
• bundledDependencies: ожидает массив имен пакетов, которые будут связаны с проектом. Используйте флаг –save-bundle с командой install, чтобы зависимость была добавлена ​​в список bundledDependencies.
• peerDependencies: одноранговые зависимости нужны для определения модулей, от которых зависит ваш проект. При отсутствии одноранговых зависимостей npm выдаст предупреждение.

Как вы, наверное, видели раньше, зависимости могут принимать разные форматы, что позволяет указать версии или диапазон версий, которые можно использовать. Например:

• 2.4.2: точная версия 2.4.2
• ^2.4.2: последняя версия, совместимая с 2.4.2
• ~2.4.2: проект работает с версиями 2.4.2, 2.4.3, 2.4.4,…
• ~2.4: задает версии 2.4, 2.5, 2.6,…
• 2.4.x: работает с любой патч-версией пакета 2.4.
• 2.x: задает любую младшую версию для версии 2.
• >=2.4: версия 2.4 и выше. Вы также можете использовать символы <, <= или >.
• 2.4.2 3.1.1: любая версия в диапазоне от 2.4.2 до 3.1.1

Чтобы задать сразу несколько диапазонов версий, разделите их с помощью ||.

Другие полезные ключи

Файл package.json поддерживает множество настроек, которые при желании можно использовать для настройки вашего проекта. Давайте кратко рассмотрим некоторые из наиболее полезных конфигураций:

• browser: можно использовать вместо ключа main для проектов, которые предназначены для работы в браузере, а не на сервере.
• private: если для этого ключа установлено значение true, проект не сможет быть публичным в репозитории npm. Это позволяет предотвратить случайную публикацию проекта.
• engine: позволяет указать конкретные версии Node.js или npm, с которыми работает проект. Для этого требуется объект с ключом node или npm и значение, которое задает версию (определяется так же, как версии и диапазоны зависимостей).
• homepage: URL-адрес домашней страницы проекта.
• bugs: URL-адрес, по которому можно сообщить о проблемах и ошибках. Часто это URL-адрес страницы проекта на Github.
• files: этот опциональный ключ принимает массив файлов, которые включаются, когда проект добавляется в зависимость от другого проекта. Имена файлов или пути могут использовать маску. Когда ключ files не указан, используется значение по умолчанию [“*”] – оно означает, что все файлы будут включены. Некоторые файлы и папки (среди них .git и nome_modules) всегда игнорируются.

Теперь у вас должно быть довольно хорошее общее представление о том, что может включать конфигурация package.json. Вы также можете обратиться к официальной документации, чтобы получить подробную информацию обо всех возможных ключах конфигурации.