Ты, я и пакет.json

¿Эспаньол? Puedes Encontrar la ersión Traducida de este artículo aquí: Tú, yo, y package.json

Если вы работали в проекте node.js или на стороне клиента, есть довольно хороший шанс, что вы увидели файл под названием Package.json и что вы ткнули вокруг его содержимого. Несмотря на то, что там есть много вещей, с которыми вы, вероятно, очень хорошо знакомы, вы, возможно, столкнулись с какими -то вещами, которые не совсем уверены, что это значит или даже как он попал там в первую очередь.

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

Но Перво на первый взгляд:

Что такое файл package.json?

Исторически узел использовал инструмент под названием npm управлять пакетом и зависимостями. Этот инструмент, который обычно устанавливается вдоль узла, имеет две основные задания:

Публикация вашего проекта в государственный реестр NPM (Таким образом, другие пользователи могут скачать его как зависимость для своих проектов) Анкет
Управляйте зависимостями вашего собственного проекта.

Чтобы иметь возможность сделать это, клиент NPM создает и использует файл с именем Package.json Анкет Этот файл содержит информацию о проекте, такой как:

Имя.
Версия.
Зависимости.
Репозиторий.
Авторы).
Лицензия.

И более.

Кроме того, а также ведение записи, используя этот файл, целостность проекта может быть гарантирована для всех, кто получает копию. Это означает, что любой пользователь в любой момент времени сможет получить доступ к одному и тому же набору Подобные совместимые зависимости . В некотором смысле, мы можем думать о Package.json Файл как манифест нашего проекта. Здесь следует иметь в виду, что, хотя зависимости, перечисленные в файле Package.json, должны быть похожими и совместимыми с исходными, не гарантируется, что проект сможет работать без каких -либо проблем, если значительное время пройдет с момента Первоначальное объявление _ (может быть случаи, когда изменения были введены в другой версии пакета, которая также считается совместимой, но может сломать некоторую функциональность). Для этого используется Заблокируйте файлы Рекомендовано.

Давайте посмотрим на пример, рассмотрив следующий сценарий:

Два разработчика работают над одним и тем же проектом, с независимыми копиями в своих компьютерах. Dev #1 решает, что для завершения новой функции ему нужно будет использовать новую библиотеку в проекте.

Без какого -либо управления зависимостями ему нужно было бы сделать одну из двух вещей:

Вручную загрузите библиотеку в каталог проекта и сохраните копию, которая должна быть включена везде, где хранится проект, потенциально увеличивая объем данных, которые необходимо передать в любое время, когда новый разработчик получает копию.
Загрузите копию библиотеки, не сохраняя копию, но позволяя каждому человеку, работающему над проектом (настоящее и будущее) Знайте, что им нужно получить его копию и убедиться, что они используют ту же версию. (Хороший способ завести новых друзей, но не так хорош с точки зрения управления временем) Анкет

С помощью инструмента управления зависимостями, таким как NPM, ни один из этих шагов больше не требуется. Любой, кто получает копию проекта, сейчас и навсегда (Пока пакет не был не опубликован) , сможет установить каждую из зависимостей без необходимости передачи фактических копий их. В результате фактический проект, который он хранится в репозитории и общий, является намного легче, а избыточные данные не передаются.

Стоит отметить, что, несмотря на то, что большая часть информации, содержащейся в файле Package.json, представляется конкретной для публикации проектов в реестре NPM, мы все еще можем использовать NPM для управления другими видами проектов, которые никогда не будут опубликованы там, такие как веб -и/или мобильные приложения, игры и другие.

В качестве последнего примечания о управлении зависимостями, некоторое время назад, мои очень хорошие друзья в Facebook (Примечание: они действительно не знают, что мы друзья … еще:() запустил аналогичный инструмент под названием yarn , который для всех намерений и целей этой статьи способен выполнять те же две задачи Мы упомянули выше, и его использование файла package.json одинаково, если не указано явно.

Как создать файл package.json

Одно правило, чтобы позвонить их всем (?)

Перед созданием файла package.json есть одно правило: файл должен быть в действительном формате JSON и должен соблюдать Json Style Spec.

Имея это в виду, существует 2 разных способа создания файла: вручную или с использованием NPM/Yarn CLI:

Создание Package.json вручную

Если по какой -либо причине вариант использования CLI NPM/YARN недоступна, и нам действительно нужно создать файл вручную, нам нужно добавить новый файл (названный package.json ) к корню проекта, содержащего следующие поля:

имя Анкет
Версия Анкет

Все остальное поле (перечислен в следующем разделе) Необязательно, хотя и рекомендуется.

Создание пакета.

Это рекомендуемый способ сделать это. Создание файла package.json может быть выполнено путем запуска любой из этих команд (в зависимости от того, какой диспетчер пакетов вы используете) в корневом каталоге проекта:

npm init

или же

yarn init

В зависимости от того, используется ли NPM или пряжа, необходимо предоставить определенную информацию перед созданием файла:

После завершения, совершенно новый Package.json Файл будет создан в корневом каталоге проекта.

Быстрая подсказка : Если вам нужно быстро создать файл package.json с значениями по умолчанию, вы можете запустить:

npm init -y

или же

yarn init -y

Разделы файла package.json

После создания файла package.json, либо вручную, либо с использованием CLI, мы найдем внутри большого объекта с разными ключами и значениями (Как начальное изображение этой статьи) Анкет Кроме того, со временем и новые зависимости/конфигурации включены, новые ключи и значения также будут включены здесь. Ниже приведен список наиболее распространенных, с которыми мы, вероятно, столкнулись в какой -то момент:

Примечание : Этот список включает только свойства, официально объявленные и поддерживаемые NPM. Существует несколько внешних библиотек, которые также поддерживают ключи для чтения из файла package.json (т.е. Шутка и собственность “шутка”)

имя

Это одно из двух необходимых полей, которые необходимо включить в файл (вместе с версией) Анкет Это строка, которая представляет имя текущего проекта, а также работает в качестве уникального идентификатора в случае опубликованного проекта в реестре.

Правила:

Имя должно быть строчным и не может начинаться с периода или подчеркивания.
Максимальная длина имени – 214 символов и должна быть безопасным для URL (Подробнее о безопасных символах URL -адресов можно найти Здесь , раздел 2.3) .

Несколько других вещей, которые нужно помнить:

Если проект будет опубликован в реестре NPM, имя должно быть уникальным и доступным (Никаких других проектов, опубликованных перед использованием того же имени) Анкет
Несмотря на то, что это считается хорошей практикой для использования связанных имен, если пакет принадлежит определенной технологии (Как использование React- {что-то} для библиотек React) , также рекомендуется не использовать узел или JS во имя.

версия

Другое обязательное поле вместе с именем. Это строка, указывающая текущую версию проекта. Проекты Node.js и JavaScript обычно соблюдают соглашения, определенные в семантической версии (или Semver) , что определяет следующую структуру для версий:

MAJOR.MINOR.PATCH

Больше информации о Semver.

описание

Строка с коротким объяснением того, о чем проект. Если пакет когда -либо опубликован, этот текст также будет иметь отношение к результатам поиска.

ключевые слова

То же самое, что и описание, но вместо текста, это множество строк, которые включают соответствующие термины, которые можно использовать для поиска пакета.

домашняя страница

Строка с действительным URL -адресом для веб -сайта проекта.

ошибки

Строка с действительным URL -адресом, где пользователи могут сообщать о проблемах, найденных в проекте. Обычно Проблемы URL -адрес репозитория используется для этого.

лицензия

Строка, которая указывает тип лицензии, по которой выпускается этот проект. Это может быть личным, коммерческим, открытым или частным.

Больше информации о доступных лицензиях.

автор

Это может быть либо строка, либо объект с информацией о создателе проекта.

Если это объект, должен быть в следующем формате:

имя.
Эл. адрес.
URL

И если это строка:

"Name  (URL)"

участники

Подобно автору, это множество объектов (или множество струн) с информацией о участниках проекта.

файлы

Массив струн или узоров (например, *.js) из файлов, которые будут включены в проект, если он когда -либо опубликован в реестре. Если этот раздел не определен, каждый файл (Это не исключено в таком файле, как .gitignore) будет включен.

Некоторые вещи должны помнить об этом:

По умолчанию каждый файл, указанный внутри .gitignore будет исключено из публикации.
Вместо добавления файлы раздел, а .npmignore Файл может быть включен в корень проекта со списком файлов, чтобы исключить из публикации (Подобно то, что делает .gitignore) Анкет
Некоторые файлы всегда будет включен , независимо от явного исключения. Среди этих файлов: package.json, readme, изменения/ChangeLog/история, лицензия/лицензия, уведомление и файл, определяемый как точка входа в приложение (Подробнее об этом в следующем разделе)
Некоторые файлы всегда будет игнорироваться , независимо от явного включения. Список этих файлов можно найти Здесь Анкет

главный

Строка, которая определяет точку входа проекта. Если проект является пакетом/библиотекой, это файл, который будет импортирован всякий раз, когда кто -то это требует. Например:

Если ваш проект называется Супер-удивительная библиотека и пользователь устанавливает его, а затем в их приложении, которое они делают:

const superAwesomeLibrary = require("super-awesome-library");

суперсомелибрия Переменная будет иметь содержимое того, что ваш основной файл экспортирует, поэтому, если в вашем файле Package.json есть объявление, такое как:

{
  "main": "lib/foo.js"
}

тогда суперсомелибрия Переменная будет содержать контент, который экспортируется в lib/foo.js Анкет

Если этот раздел опущен, то содержимое index.js Файл, который живет в корневом каталоге проекта, будет использоваться.

бин

Строка (Если это только один) или объект (Если это несколько) Определение сценариев, которые будут установлены и будут доступны в качестве команд в пути. После установки пакета символическая ссылка будет создана из /usr/local/bin в соответствующий файл внутри проекта и будет доступен в качестве программы командной строки.

Например, допустим, у нас есть файл с именем cli.js Внутри нашего проекта, и мы хотим сделать его доступным для пользователей, чтобы позвонить ему непосредственно с их терминалов. Способ достижения этого – включить одну строку как бин Inside Package.json следующим образом:

{
  "name": "super-awesome-library",
  "bin": "cli.js"
}

Теперь содержимое cli.js может быть использован, запустив все, что мы положили как имя проекта в терминале:

super-awesome-library

В то время как пользователь выполняет это дружелюбное имя, на самом деле, что -то подобное происходит “За кулисами” :

node cli.js

И тогда все, что находится в этом файле, будет запущено.

Если вместо этого у нас есть несколько файлов, которые мы хотим превратить в исполняемые сценарии, мы можем вместо этого использовать формат объекта. Это добавит символическую ссылку для каждого Ключевая стоимость пара, используя ключ как команда, которая будет доступна потом:

{
  "bin": {
    "script-1": "super-h4x0r-script1.js",
    "script-2": "on-your-left.js"
  }
}

С этим объектом, оба “Script-1” и “Script-2” будет включен в путь, каждый из которых указывает на соответствующий файл .js, который был их парой внутри объекта Bin.

Это то, что многие известные пакеты, такие как Nodemon или Реактивно-родная , включите, чтобы мы могли использовать их в качестве команд терминалов непосредственно без необходимости запуска Узел, что-то вроде-это-файл-это Анкет

человек

Строка или массив струн, определяя один (или много) Файл (ы), которые будут доступны/показаны, если человек Команда запускается для этого проекта.

каталоги

Объект, определяющий структуру проекта и где каждая папка находится для определенных разделов. Наиболее распространенными являются бин , Док , пример , lib , Человек , тест Анкет

{
  "bin": "./bin",
  "doc": "./doc",
  "lib": "./lib"
}

репозиторий

Объект, определяющий, где этот проект хранится и может быть найден для вклада. Объект имеет следующий формат:

{
  "type": string,
  "url": string
}

Где Тип относится к типу репозитория (например, SVN или GIT) и URL является действительным URL, где его можно найти.

Пример:

{
  "type": "git",
  "url": "https://github.com/my-user/super-awesome-project"
}

сценарии

Команды, определяющие объект, который можно использовать с NPM/прямой CLI для проекта. Некоторые сценарии предопределены и зарезервированы и могут использоваться без определения их, таких как запустить, установить, предварительно установку, предварительно тест и посттест среди других. (Полный список можно найти здесь ) .

Точно так же мы можем определить наши собственные сценарии и использовать для них пользовательские имена и инструкции. Это очень полезно для создания ярлыков и/или комбинированных задач без необходимости запоминания полных команд и/или параметров каждый раз.

Например, давайте притворимся, что у нас есть приложение, которому нужно запустить задачу для министерства файлов JS, прежде чем создавать новую версию, и мы делаем это с помощью скрипта, который живет в Задачи/minify.js и передача флага или парама, который использует внутреннюю. Обычно мы бегали Узел задачи/minify.js -someflag -МАЙБЕАНА Каждый раз, когда мы хотим достичь этого (И нам нужно также вспомнить имя флагов) Анкет Однако, если мы вместо этого добавим его в сценарии NPM, мы могли бы сделать что -то вроде:

"scripts": {
  "minify": "node tasks/minify.js --someflag --maybeanother"
}

А затем беги:

npm run minify

Это достигает точно такого же результата. Крутая вещь об этом заключается не только в том, чтобы не только запоминать точные команды, которые нам нужно выполнять каждый раз, но также и сценарии NPM могут быть объединены и выполнены последовательно, поэтому мы можем создавать сложные задачи и даже запускать некоторые автоматически, если мы используем какие -либо из Pre крючки (как предварительный тест или подготовка) Анкет

Например, допустим, что мы хотим запустить ту же самую задачу, а также запустить наш код через Linter, прямо перед тем, как запустить тесты нашего приложения. Для этого мы могли бы добавить что -то подобное (Притворяться, что код приложения живет в папке src :

"scripts": {
  "pretest": "node tasks/minify.js --someflag --maybeanother && eslint src"
}

Или мы могли бы включить его непосредственно как часть тест Скрипт (В этом примере используется Jest, но вы можете заменить его на мокко/ava/лента/и т. Д. Или инструмент по вашему выбору) :

"scripts": {
  "test": "node tasks/minify.js --someflag --maybeanother && eslint src && jest"
}

В качестве последнего примечания об этом, эти сценарии должны быть запускаются как NPM запустить ‘скрипт’ Если это не один из предопределенных/зарезервированных NPM (Перечислен в начале этого раздела) . Однако, если вы используете пряжу, вы можете опустить запустить Отчасти полностью и просто сделайте пряжа ‘скрипт’ , независимо от этого, это предопределенный сценарий или нет.

конфигурация

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

Чтобы установить значение конфигурации, мы можем сделать это внутри файла package.json:

{
  "name": "my-app",
  "config": {
    "port": 8000
  }
}

И затем, значения могут быть ссылаются из кода, используя process.env.npm_package_config_ {value} , как это:

const express = require('express');
const app = express();
const port = process.env.npm_package_config_port;

app.get('/', (req, res) => res.send('Hello!'));

app.listen(port, () => console.log(`App listening on port ${port}!`));

Эти значения конфигурации могут быть изменены извне файла Package.json в любое время, выполнив:

Набор конфигурации NPM {имя проекта}: {config Quey} {значение config}

Для нашего предыдущего примера мы могли бы сделать что -то вроде этого:

npm config set my-app:port 3000

зависимости

Объект, который хранит имя и версию каждой установленной зависимости (и спасен) Во время истории проекта. Каждый раз, когда кто -то получает новую копию этого проекта и работает NPM Установка , все эти зависимости будут установлены (с новейшей совместимой версией) Анкет Эти зависимости, а также следующие две категории определены со следующим форматом:

"name-of-the-dependency": "(^|~|version)|url"

Некоторые примеры:

"dependencies": {
  "backbone": "1.0.0",
  "lodash": "^4.6.1",
  "mocha": "~3.5.3",
  "super-mega-library": "https://example.com/super-mega-library-4.0.0.tar.gz"
}

Эти зависимости могут иметь либо установленную и сохраненную версию, либо действительный URL -адрес, где пакет с текущей версией можно получить (Этот URL также может быть локальным путем внутри того же компьютера) .

Каковы символы ^ и ~ в начале версий?

Каждая установленная зависимость может иметь символ, определяющий диапазон приемлемых совместимых версий. Это 2 общего пользования, но можно найти полный список Здесь Анкет

Другими словами, эти символы добавляют инструкции о том, как эту зависимость следует обращаться в следующий раз, когда NPM Установка случается:

Если у версии есть каретка (^) : Разрешить установить другую версию, если это просто незначительное изменение (Второй номер версии) Анкет Если не найдено разных второстепенных версий, будет установлена та же версия.
Если у версии есть тильда (~) : Позволяет установить другую версию, если это просто изменение патча (Последний номер версии) Анкет Если не найдено разных патчей, будет установлена та же версия.
Если у версии просто есть номер и никаких символов : То же самая определенная версия должна быть установлена.

Например, с зависимостью, указанными выше, если мы запустим NPM Установка и новые версии доступны:

Магистраль и Super-Mega-Library останется в использовании тех же версий (1.0.0 и 4.0.0 соответственно).
Лодаш Может либо установить ту же версию, либо любые версии между 4.6.1 а также 4.9.9 , но никогда ничего равного 5.x.x или выше.
Мокко Может либо установить ту же версию, либо любые версии между 3.5.3 и 3.5.9 , но никогда не выше этого.

DevDependencies

Тот же формат, что и зависимости, перечисленные выше, но этот раздел будет включать все зависимости, которые использует проект, но не необходимы для производственной среды (Как инструменты тестирования, локальные Dev -серверы, инструменты оптимизации и т. Д.) . Любой компьютер, который получает копию этого проекта и имеет Производство установить как Node_env Переменная не установит зависимости, перечисленные в этом разделе.

Перезависимости

Это также использует тот же формат, но эти зависимости, хотя и не обязательно установлены, определяют совместимость, необходимую для правильной работы этого приложения/пакета. Например, если мы разрабатываем библиотеку, которая совместима только с версией 16 React, нам нужно сделать что -то вроде этого:

"peerDependencies": {
  "react": "16.0.0"
}

Старые версии NPM (1 и 2) Используется для автоматической установки этих резервуаров, но это больше не так. Начиная с версией 3, если совместимая версия не найдена при установке этого проекта, будет инициировано предупреждение.

двигатели

Объект, где мы можем определить минимальные версии узла и NPM, которые поддерживает этот проект. Это определено в следующем формате:

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

Когда проект будет установлен, будет запущен чек, чтобы обеспечить совместимость. Если это не будет выполнено, процесс установки остановится.

Как и в случае с зависимостями, мы можем использовать диапазоны (как **> = ** , **^* * , ** ~ ** , так далее.) определить совместимые версии.

Дополнительная информация

Несмотря на то, что это самые распространенные вещи, которые мы найдем и используем в файле Package.json, все еще есть некоторые дополнительные, которые могут быть интересными или полезными для проверки. Для получения дополнительных ссылок я бы порекомендовал просматривать официальные документы NPM на регулярной основе, поскольку она постоянно обновляется в любое время, когда выпускается новая версия.

Полезные ссылки:

Первоначально опубликовано в моем блоге в Xabadu.dev

Оригинал: “https://dev.to/xabadu/you-me-and-package-json-1dc2”