peerdependencies npm что это
npm Peer Dependencies
Understanding when and why to use npm peerDependencies
In this article I hope to clarify what npm Peer Dependencies are and especially when you should use them. Peer Dependencies are listed in the package.json file in the peerDependencies object.
To get the most out of this article you should have at least an introductory understanding of npm.
Contents
The Scenario
To keep it real, let’s assume you’re creating an Angular Library or even just a simple JavaScript file that exports some functions.
Your project relies on packages from the npm Registry. These packages are your project’s dependencies.
You want to create your own npm package from your project. So you use npm pack to generate an npm package from your project. You might even decide to publish it to the npm Registry.
Other teams will add your package as a dependency in their own projects. We use Dependencies and Peer Dependencies in package.json to tell these other projects what packages also need to be added for our package to work.
So, at their most basic level here is how Dependencies and Peer Dependencies work:
Dependencies
Dependencies are listed in the package.json file in a dependencies object.
Peer Dependencies
Peer Dependencies are listed in the package.json file in a peerDependencies object.
By adding a package in peerDependencies you are saying:
Adding Dependencies
So, we add dependencies in the package.json file of our npm package folder. Let’s look at exactly how we add packages as dependencies and some examples of package dependencies.
Adding a Dependency
A Dependency is an npm package that our package depends on in order to be able to run. Some popular packages that are typically added as dependencies are lodash, request, and moment.
We add a regular dependency like this:
npm adds the package name and version to the dependencies object in our project’s package.json file.
Adding a Peer Dependency
Peer Dependencies are used to specify that our package is compatible with a specific version of an npm package. Good examples are Angular and React.
To add a Peer Dependency you actually need to manually modify your package.json file. For example, for Angular component library projects, I recommend adding angular/core as a peer dependency. So if you wanted to specify that your package is built for Angular 7, you could include something like this:
About Conflicts
If you have read my previous articles, you know I like you to be able to do this stuff along with me! So feel free to work along with me for this little npm experiment.
conflict-test Project
To get started let’s create a trivial test project. I am going to name mine:
conflict-test
I created it like this:
I then manually edited the package.json file and added two dependencies:
These todd-a and todd-b packages also have their own dependencies:
todd-a
todd-b
So here is the rule:
npm deals with version conflicts by adding duplicate private versions of the conflicted package.
An Approach to Peer Dependencies
Sometimes, having two versions of the same package is fine. However, some packages will cause conflicts when there are two different versions of them in the same code base.
For example, assume our component library was created using Angular 5. We wouldn’t want our package adding another completely different version of angular/core when someone adds it as a dependency to their Angular 6 application.
The key is:
We don’t want our library adding another version of a package to node-modules when that package could conflict with an existing version and cause problems.
peerDependencies or dependencies?
So this brings us to the main question for our dependencies:
When my package depends on another package, should I put it in dependencies or peerDependencies?
Well, as with most technical questions: it depends.
Peer Dependencies express compatibility. For example, you will want to be specific about which version of Angular your library is compatible with.
The Guidelines
Favor using Peer Dependencies when one of the following is true:
Angular as a Dependency
Given that you are going to specify in your documentation that your library is a set of Angular Components and Services, you may be asking the question:
“Do I even need to specify angular/core as a dependency? If someone is using my library, they will already have an existing Angular project.”
Yes, we can usually assume that for our Angular specific library the Workspace will already have the Angular packages available. Hence, technically we wouldn’t need to bother adding them to our list of dependencies.
However, we really do want to tell the developer which Angular versions our library is compatible with. So I recommend the following approach:
This way developers will see a warning if they try to use your Angular 7 library in their Angular 6 project. Don’t bother adding the other Angular packages. You can assume if they have angular/core, they have the other Angular libraries.
In Conclusion
Управление зависимостями JavaScript
Всем привет! Меня зовут Слава Фомин, я ведущий разработчик в компании DomClick. За свою 16-ти летнюю практику я в первых рядах наблюдал за становлением и развитием JavaScript как стандарта и экосистемы. В нашей компании мы используем JavaScript, в первую очередь, для продвинутой front-end разработки и успели перепробовать достаточно большое количество различных технологий, инструментов и подходов, набить много шишек. Результатом этого кропотливого труда стал ценнейший опыт, которым я и хочу поделиться с вами.
Изначально, я хотел рассказать о том как мы работаем над сотнями пакетов с использованием монорепозиториев, но в результате пришел к выводу, что для углубления в эту довольно сложную тему стоило бы сначала объяснить более простые концепции. В итоге решил оформить весь материал в виде блога с небольшими постами, в которых буду подробнее раскрывать отдельные темы, плавно водя читателя от простых вопросов к сложным. Надеюсь, это сделает материал полезным не только состоявшимся профессионалам, но и новичкам.
Вот список тем, которые я планирую затронуть в этом блоге:
Итак, не будем терять времени!
…Мы подобны карликам, усевшимся на плечах великанов; мы видим больше и дальше, чем они, не потому, что обладаем лучшим зрением, и не потому, что выше их, но потому, что они нас подняли и увеличили наш рост собственным величием…
Я думаю мало кто станет отрицать, что того успеха, который сейчас наблюдается в области веб-разработки, мы смогли добиться во многом благодаря всем тем людям, которые создали и поддерживают каждый день тысячи полезных библиотек и инструментов. Действительно, вы можете представить себе эффективную разработку современного веб-приложения без использования фреймворков, библиотек и инструментов?
Несмотря на огромный прогресс в фундаментальных веб-технологиях, создание даже мало-мальски сложного приложения потребовало бы достаточно высокой квалификации разработчиков и написания огромного количества базового кода с нуля. Но, слава богу, существуют такие решения, как Angular, React, Express, Lodash, Webpack и многие другие, и нам не нужно каждый раз изобретать колесо.
Немного истории JavaScript
Мы можем вспомнить «дикие времена», когда код популярных библиотек (таких как jQuery) и плагины к ним разработчику нужно было напрямую скачивать с официального сайта, а затем распаковывать из архивов в директорию проекта. Разумеется, обновление таких библиотек происходило точно так же: вручную. Сборка такого приложения тоже требовала ручного и достаточно творческого, уникального подхода. Про оптимизацию сборки я даже не стану упоминать.
К огромному счастью, которое более молодые разработчики вряд ли смогут сейчас испытать, эти времена ручного управления зависимостями в прошлом. Сейчас мы имеем хоть и не самые совершенные, но вполне рабочие инструменты, которые позволяют взять под контроль управление зависимостями даже в довольно сложных проектах.
Node.js приходит на помощь
Современную веб-разработку уже совершенно невозможно представить без Node.js, технологии, которая изначально разрабатывалась для сервера, но впоследствии стала платформой для любых JavaScript-проектов, как front-end приложений, так и всевозможных инструментов, а с популяризацией SSR граница между средами начала окончательно стираться. Таким образом, менеджер пакетов для Node.js (Node Package Manager, или npm), постепенно стал универсальным менеджером пакетов для всех библиотек и инструментов, написанных на JavaScript.
Также стоит заметить, что до появления ESM стандарт языка JavaScript в принципе не имел концепции модулей и зависимостей: весь код просто загружался через тег script в браузере и выполнялся в одной большой глобальной области видимости. По этой причине разработчики Node внедрили собственный формат модулей. Он был основан на неофициальном стандарте CommonJS (от слов «распространенный/универсальный JavaScript», или CJS), который впоследствии стал де-факто стандартом в индустрии. Сам же алгоритм поиска зависимостей Node (Node.js module resolution algorithm) стал стандартом представления пакетов в файловой системе проекта, который сейчас используется всеми загрузчиками и инструментами сборки.
Пакет всему голова
Как было упомянуто выше, Node.js ввел свой формат представления и поиска зависимостей, который сейчас де-факто является общим стандартом для JavaScript-проектов.
В основе системы лежит концепция пакета: npm-пакет — это минимальная единица распространения кода на JavaScript. Любая библиотека или фреймворк представляются как один или несколько связанных пакетов. Ваше приложение также является пакетом.
Перед публикацией пакет, как правило, компилируется, а потом загружается в хранилище, которое называется npm registry. В основном используется централизованный официальный npm registry, который находится в публичном доступе на домене registry.npmjs.org. Однако использование частных закрытых npm registry также распространено (мы в ДомКлике активно используем такой для внутренних пакетов). Другие разработчики могут установить опубликованный пакет как зависимость в свой проект, загрузив его из registry. Это происходит автоматически при помощи менеджера пакетов (вроде npm).
Найти нужный пакет или изучить их список можно на официальном сайте npm.
Опубликованный пакет физически представляет собой версионированный архив с кодом, который готов к выполнению или внедрению в другой проект. Этот код может представлять собой библиотеку, которую вы можете включить в свое приложение (например, lodash), либо полноценную программу, которую можно напрямую вызвать у вас на компьютере (например, webpack).
При этом код из одного пакета может обращаться к коду из другого. В этом случае говорят, что один пакет зависит от другого. У каждого пакета может быть множество зависимостей, которые, в свою очередь, также могут иметь свои зависимости. Таким образом, связи между всеми пакетами образуют дерево зависимостей:
На изображении показан результат команды npm ls — дерево зависимостей проекта, в котором установлено всего два пакета: HTTP-сервер Express (с множеством дочерних зависимостей) и библиотека Lodash (без зависимостей). Обратите внимание, что одна и та же зависимость debug встречается 4 раза в разных частях дерева. Надпись deduped означает, что npm обнаружил дублирующиеся зависимости и установил пакет только один раз (подробнее о дубликации мы поговорим в следующих постах).
Манифест пакета
Что же является пакетом и как мы можем его создать? По сути, пакетом может являться любая директория, содержащая специальный файл-манифест: package.json. Он может содержать множество полезной информации о пакете, такой как:
Описание зависимостей пакета
Манифест пакета содержит ряд опциональных полей, которые позволяют задавать список зависимостей:
Каждое из этих полей является JSON-объектом, где в качестве ключа указывается название пакета, а в качестве значения — диапазон версий, которые поддерживаются в вашем проекте.
Пример:
Давайте рассмотрим назначение каждого поля в отдельности.
dependencies
devDependencies
Поле devDependencies позволяет задать список зависимостей, которые необходимы только на этапе разработки пакета, но не для выполнения его кода в рантайме. Сюда можно отнести всевозможные инструменты разработки и сборки, такие как typescript, webpack, eslint и прочие. Если ваш пакет будет устанавливаться как зависимость для другого пакета, то зависимости из этого списка установлены не будут.
peerDependencies
Поле peerDependencies играет особую роль при разработке вспомогательных пакетов для некоторых инструментов и фреймворков. К примеру, если вы пишете плагин для Webpack, то в поле peerDependencies вы можете указать версию webpack, которую ваш плагин поддерживает.
Если ваш пакет будет установлен в проекте, где указанная зависимость отсутствует, либо условие по версии не удовлетворяется, то менеджер пакетов сообщит разработчику об этом.
При установке вашего пакета зависимости из поля peerDependencies автоматически не устанавливаются, разработчик должен сам установить их в свой родительский проект, прописав в манифесте своего пакета. Это также гарантирует, что в проекте будет использоваться только одна версия зависимости без дубликатов. Ведь если в проекте будет установлено несколько разных версий, скажем, Webpack, то это может привести к серьезным конфликтам.
optionalDependencies
И последнее поле optionalDependencies позволяет вам указать некритические зависимости, без которых ваше приложение сможет всё равно выполнять свою работу. Если менеджер пакетов не сможет найти или установить такую зависимость, то он просто проигнорирует её и не вызовет ошибки.
Зависимости во front-end проектах
Выше мы рассмотрели четыре способа задания различных зависимостей для вашего проекта. Однако не стоит забывать, что эта система была изначально придумана для приложений и библиотек на Node.js, которые выполняются напрямую на машине пользователя, а не в особой песочнице, коей является браузер. Таким образом, стандарт никак не учитывает особенности разработки front-end приложений.
Если кто-то вам скажет, что один способ определения npm-зависимостей для front-end приложений является правильным, а другой нет, то не верьте: «правильного» способа не существует, потому что такой вариант использования просто не учтен в node и npm.
Однако для удобства работы над front-end приложениями я могу предложить вам проверенный временем и опытом формат определения зависимостей. Но для начала давайте попробуем разобраться, чем отличается front-end проект от проекта на Node.js.
Обычно конечная цель Node.js-разработчика заключается в том, чтобы опубликовать созданный им пакет в npm registry, а уже оттуда этот пакет скачивается, устанавливается и используется пользователем как готовое ПО или как библиотека в составе более сложного продукта. При этом зависимости из поля dependencies в манифесте пакета устанавливаются в проект конечного пользователя.
Семантическое версионирование
В экосистеме npm принят стандарт версионирования пакетов semver (от слов Semantic Versioning (семантическое версионирование)).
Суть стандарта заключается в том, что версия пакета состоит из трех чисел: основной (major) версии, младшей (minor) версии и patch-версии:
Например: 3.12.1.
Семантическим этот вид версионирования называется потому, что за каждым числом версии, а точнее, за увеличением числа стоит определенный смысл.
Увеличение patch-версии означает, что в пакет были внесены незначительные исправления или улучшения, которые не добавляют новой функциональности и не нарушают обратную совместимость.
Увеличение minor-версии означает, что в пакет была добавлена новая функциональность, но совместимость сохранилась.
Увеличение же major-версии означает, что в пакет были внесены серьезные изменения API, которые привели к потере обратной совместимости и пользователю пакета, возможно, необходимо внести изменения в свой код, чтобы перейти на новую версию. О таких изменениях и порядке миграции на новую версию обычно можно прочитать в файле CHANGELOG в корне пакета.
Нестабильные версии
Версии пакетов до 1.0.0, например, 0.0.3 или 0.1.2, в системе semver также имеют определенный смысл: такие версии считаются нестабильными и повышение первого ненулевого числа версии должно расцениваться как изменение с потенциальным нарушением обратной совместимости.
Продолжение следует
Мы рассмотрели самые основы управления зависимостями в JavaScript: узнали, что такое пакет, как он определяется и как задаются зависимости. В следующем посте мы подробнее рассматриваем, как на практике работает semver, как правильно прописывать диапазоны версий и обновлять зависимости.
В чем разница между зависимостями, devDependencies и peerDependencies в пакете npm.файл json?
документация отвечает на мой вопрос очень плохо. Я не понял этих объяснений. Кто-нибудь может сказать проще? Может быть, с примерами, если трудно выбрать простые слова?
10 ответов
резюме важных различий в поведении:
dependencies установленных на обоих:
dependencies устанавливаются транзитивно: если A требует B, и B требуется C, затем c устанавливается, иначе B не может работать, и A.
devDependencies не устанавливаются транзитивно. Е. Г. нам не нужно Тест Б чтобы проверить, так что зависимости B-тестирования могут быть опущены.
опции не обсуждаются здесь:
в разделе devDependencies
так как у вас фактический источник, понятно, что вы хотите его разработать, поэтому по умолчанию оба dependencies (так как вы, конечно, должны работать, чтобы развиваться) и devDependency зависимости также установлены.
Если, однако, вы только конечный пользователь, который просто хочет установить пакет, чтобы использовать его, вы будете делать из любого каталога:
параметр false по умолчанию, так как это гораздо менее распространенный случай.
peerDependencies
с регулярными зависимостями, вы можете иметь несколько версии зависимости: он просто установлен внутри node_modules зависимости.
Е. Г. если dependency1 и dependency2 как зависит dependency3 в разных версиях дерево проекта будет выглядеть так:
Плагины, однако, являются пакетами, которые обычно не требуют другого пакета, который называется хоста в этом контексте. Вместо этого:
я думаю, что это экземпляр инверсия управления шаблон дизайна.
прототипическим примером одноранговых зависимостей является Grunt, хост и его плагины.
например, на плагине Grunt, таком как https://github.com/gruntjs/grunt-contrib-uglify, вы увидите, что:
потом, когда пользователь будет использовать плагин, он будет неявно требовать плагин от Gruntfile добавить grunt.loadNpmTasks(‘grunt-contrib-uglify’) линия, но это grunt что пользователь будет звонить напрямую.
это не сработало бы, если бы каждый плагин требовал другой версии Grunt.
руководство
я думаю, что doc отвечает на вопрос довольно хорошо, возможно, вы недостаточно знакомы с менеджерами узлов / других пакетов. Я, вероятно, понимаю это только потому, что знаю немного о Ruby упаковщик.
эти вещи будут установлены при выполнении npm link или npm install из корня пакета и могут управляться как любой другой параметр конфигурации npm. Увидеть НПМ-конфиг(7) для более по теме.
а затем в npm-config (7) Найдите dev :
в качестве примера mocha обычно будет devDependency, так как тестирование не требуется в производстве, в то время как express будет зависимостью.
сохранить пакет пакета.в JSON как зависимости dev:
есть некоторые модули и пакеты, необходимые только для развития, которые не нужны в производстве. Как говорится в документация:
Если кто-то планирует загрузить и использовать ваш модуль в своей программе, то они, вероятно, не хотят или не должны загружать и создавать внешнюю среду тестирования или документации, которую вы используете. В этом случае лучше всего перечислить эти дополнительные элементы в хэше devDependencies.
зависимости
Зависимости, которые необходимо запустить проекту, например библиотека, предоставляющая функции, вызываемые из кода.
Они устанавливаются транзитивно (если A зависит от B зависит от C, npm install on A установит B и C).
пример: lodash: ваш проект вызывает некоторые функции lodash.
в разделе devDependencies
Зависимости, необходимые только во время разработки или выпуска, например компиляторы, которые принимают ваш код и скомпилируйте его в javascript, тестовые фреймворки или генераторы документации.
Они не устанавливаются транзитивно (если A зависит от B dev-зависит от C, npm install on A установит только B).
пример: grunt: ваш проект использует grunt для создания себя.
peerDependencies
Зависимости, которые ваш проект подключает или изменяет в Родительском проекте, обычно плагин для какой-либо другой библиотеки или инструмента. Оно просто предназначено быть проверьте, что родительский проект (проект, который будет зависеть от вашего проекта) зависит от проекта, в который вы подключаетесь. Поэтому, если вы создаете плагин C, который добавляет функциональность в библиотеку B, то кто-то, делающий проект A, должен будет иметь зависимость от B, если у них есть зависимость от C.
Они не установлены (если только npm пример: grunt: ваш проект добавляет функциональность к grunt и может использоваться только в проектах, которые используют хмыкнуть.
эта документация объясняет одноранговые зависимости очень хорошо:https://nodejs.org/en/blog/npm/peer-dependencies/
кроме того, документация npm была улучшена с течением времени и теперь имеет лучшие объяснения различных типов зависимостей: https://github.com/npm/npm/blob/master/doc/files/package.json.md#devdependencies
простое объяснение, которое сделало его более ясным для меня:
при развертывании приложения необходимо установить модули в зависимостях, иначе приложение не будет работать. Модули в devDependencies не нужно устанавливать на рабочем сервере, так как вы не разрабатываете на этой машине. ссылке
Я хотел бы добавить к ответу мой взгляд на эти объяснения зависимостей
peerDependencies не совсем имел смысл для меня, пока я не прочитал этот фрагмент из блоге на тему Сиро указано выше:
что [Плагины] нужно-это способ выражения этих зависимостей между плагинами и их хост-пакет. Какой-то способ сказать: «я работаю только при подключении к версии 1.2.x моего хост-пакета, поэтому, если вы установите меня, убедитесь, что он находится рядом с совместимым хостом.»Мы называем это отношения одноранговая зависимость.
плагин ожидал конкретная версия хоста.
peerDependencies предназначены для плагинов, библиотек, которые требуют» хост » библиотеки для выполнения своей функции, но, возможно, были написаны в то время до последняя версия хоста была выпущена.
то есть, если я пишу PluginX v1 на HostLibraryX v3 и уйти, нет никакой гарантии PluginX v1 будет работать, когда HostLibraryX v4 (или даже ) является.
. но плагин не зависит на хосте.
С точки зрения плагина, это только добавляет функции для размещения библиотеки. Мне действительно «не нужен» хост, чтобы добавить зависимость к плагину, и плагины часто не буквально зависит на их хозяина. Если у вас нет хоста, плагин безвредно ничего не делает.
это значит dependencies не правильная концепция для плагинов.
еще хуже, если бы мой хозяин рассматривался как зависимость, мы бы оказались в этой ситуации, что в том же блоге упоминается (отредактировано немного, чтобы использовать этот ответ, составленный host & plugin):
но теперь, [если мы рассматриваем современную версию HostLibraryX как зависимость для PluginX,] работает npm install приводит к неожиданному графику зависимостей
я оставлю тонкий сбои, которые происходят из плагина, используя другой API [HostLibraryX], чем основное приложение для вашего воображения.
. и хозяин, очевидно, не зависит от плагина.
. в этом весь смысл плагинов. Теперь, если хозяин был достаточно хорош, чтобы включить информацию о зависимостях для все своих плагинов, что бы решить проблему, но это также представит огромную новую культурную проблему: управление плагинов!
весь смысл плагинов в том, что они могут объединяться анонимно. В идеальном мире, имея хозяина управлять ими все было бы аккуратно и аккуратно, но мы не собираемся требовать библиотеки стадных кошек.
если мы не иерархически зависимых, может быть, мы ровесники intradependent.
вместо этого, у нас есть такое понятие, как сверстники. Ни хост, ни плагин не находятся в ведре зависимостей другого. Оба живут на одном и том же уровне зависимости диаграмма.
. но это не автоматические отношения.
как насчет нет, НПМ?!
хороший peerDependency управление в плагинах сделает эту концепцию более интуитивно понятной на практике. От в блоге, еще раз.
один совет: требования к одноранговой зависимости, в отличие от требований для регулярных зависимостей, должны быть снисходительными. Вы не должны блокировать свои одноранговые зависимости до определенных версий исправлений. Было бы очень досадно, если бы один плагин Chai peer-зависел от Chai 1.4.1, в то время как другой зависел от Chai 1.5.0, просто потому, что авторы были ленивы и не тратили время на выяснение фактической минимальной версии Chai, с которой они совместимы.