📦 Как опубликовать свой пакет в npm

Подробное руководство о том, как безболезненно публиковать свои модули в npm.

Итак, вы закончили работу над lib, cli-инструментом, компонентом или некоторыми другими скриптами, которыми хотите поделиться со всем миром. Итак, пора опубликовать их на npm.

🥇 Ваш первый пакет

Предположим, вы уже используете npm для своих зависимостей. Вы установили их с помощью npm install XYZ или, если вы супер крутые 😎, с помощью пряжи

Если теперь вы хотите опубликовать свой пакет в npm, для этого есть простая команда:

npm publish

🔥 Но прежде чем мы это сделаем, у нас есть еще несколько моментов в нашем 📋 контрольном списке.

📦 Package.json

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

Однако наиболее важным было бы

name
version
description
author
license
repository
main

Поле name определяет имя, которое ваш пакет будет иметь в реестре, и люди будут устанавливать ваш пакет поверх указанного вами имени. yarn add XYZ.

Тег version определяет версию вашего пакета. Вам действительно стоит подумать об использовании семвер. Потому что, возможно, ваш пакет будет использовать множество людей. И нет ничего хуже, чем ломать производственный код людей, потому что вы вносите критические изменения, а меняете только патч-версию своего пакета. 🙈

В поле description вы должны добавить краткое и актуальное описание вашего пакета. Люди будут читать его, если будут искать ваш пакет на npmjs.org.

В поле author вы указываете свое имя и адрес электронной почты, чтобы люди знали, кто опубликовал пакет. Обычно его добавляют в виде Name <e-mail>.

Я думаю, что поле license - одно из самых забытых. Люди часто думают, что это не это важно. Однако, если вы хотите, чтобы люди использовали ваш пакет, возможно, даже в более крупных проектах вам обязательно следует добавить лицензию. Таким образом, они знают, могут ли они использовать его в коммерческих проектах, каковы ограничения и так далее.

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

Вы также можете добавить keywords, который поможет людям найти ваш пакет, если они что-то ищут на npmjs.org.

🗄 Зависимости

Итак, все мы знаем, что вы можете добавлять зависимости в свой проект. Или сохраните их как devDependencies с yarn add или yarn add -D

Теперь, если вы работаете над таким проектом, как приложение или веб-сайт, не будет такой большой разницы, если вы добавите свои зависимости как dependency или devDependency. Потому что большую часть времени они встроены в сборку браузера.

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

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

DevDependencies - это те, которые требуются для разработки. Как eslint или xo для линтинга или karma или ava для тестирования. Это важно, потому что, если кто-то установит ваш пакет поверх yarn add my-awesome-lib, devDependencies не будет установлен! Поэтому, если вы добавите request как devDependency и где-то в вашем коде у вас будет import request from 'request', это не сработает. Из-за отсутствия зависимости.

peerDependencies в основном используются, если вы пишете для чего-то плагин. Потому что для этого требуется, чтобы у пользователя уже была установлена зависимость. Например, вы хотите написать плагин для webpack, используете некоторые функции webpack и расширяете их. Если вы добавите webpack в качестве зависимости, пользователь установил бы две версии webpack: ту, которую он уже установил для процесса сборки, и ту, которая поставляется с вашим плагином.

Это чушь. Вам придется обновлять package.json при каждом выпуске нового webpack патча и обновлять версию зависимости. С peerDependencies вы говорите: Слушай, тебе нужен веб-пакет для запуска моего плагина, так что установите его, пожалуйста. Предпочтительная версия - 2.1.x Если кто-то установит webpack 2.2.x, ваш плагин тоже будет работать. Будет peerDependency version mismatch, но пока не будет критических изменений, он будет работать. Таким образом, вы даете пользователю свободу выбора версии и обновления зависимостей.

🚪 Точки входа

А теперь самое интересное. Точки входа в ваш lib / package. Этот сильно зависит от типа вашего пакета или библиотеки. Это узловой модуль? Это плагин для браузера?

Базовая точка входа будет определена над полем main. Там вы можете добавить, например, свой index.js. Если вы перекомпилируете исходный код или свяжете его, вы можете определить файл dist там.

"main": "dist/my-awesome-lib.js",

И если вы публикуете модули узла, вам подойдет этот.

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

Например, поле unpkg. Если вы опубликуете свою библиотеку на npm, она будет доступна через unpkg. Это CDN, поэтому люди могут вставлять ваши скрипты в свои скрипты, не устанавливая их через npm.

https://unpkg.com/package@version/file

В поле unpkg вы можете указать файл по умолчанию, который будет обслуживаться, если кто-то укажет https://unpkg.com/package.

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

"unpkg": "dist/my-awesome-lib.min.js",

И последнее, но не менее важное: есть еще два поля.

Поля module и jsnext:main. Которые используются современными системами сборки, такими как Webpack 2, для захвата модулей ES6.

Итак, вы создали свой lib. В основном с современным ES6. Люди хотят использовать его прямо в браузере. Так что вам нужно это транспилировать. Но поскольку у вас также есть зависимости, вам необходимо связать в него зависимости. Итак, вы создаете модуль UMD.

Но некоторые люди могут захотеть использовать ваш пакет с browserify и gulp. Или с помощью webpack 1. Итак, вам нужна транспилированная и объединенная сборка CommonJs. Однако сейчас у нас 2017 год, и теперь в моде такие вещи, как тряска деревьев. Для этого вам понадобится дополнительная сборка. Сборка модуля ES. Где большинство функций и операторов переносятся в ES2015, за исключением операторов импорта и экспорта.

Я думаю, что сейчас только Rollup поддерживает модули ES в качестве целевого вывода. (Но вы также можете транспилировать с помощью babel). Итак, если у вас есть модуль ES, вы можете установить запись в поле module и / или jsnext:main.

Таким образом, вы обслуживаете разные сборки для разных людей и разных сред.

⛓ Совместимость

Что наиболее важно для узловых модулей, вы можете определить, какая минимальная версия nodejs должна быть установлена для запуска вашего модуля. Это важно, если вы используете async / await, например, без его переноса.

"engines": {
    "node": ">=7.8.0"
  },

🚫 Игнорирует и ✅ Файлы

Хорошо, теперь у нас определены различные пакеты и сборки, и мы почти готовы опубликовать наш пакет. Однако у вас может быть журнал вещей в вашем репозитории git. Источник, возможно, ресурсы, связанные файлы и т. Д. Неразумно включать все это в свой пакет npm. Рекомендуется сохранять небольшой размер.

Во-первых, вам не нужны созданные вами файлы в репозитории git. Таким образом, вы игнорируете их в своем .gitignore

Вы также можете добавить .npmignore.

Если вы не создадите .npmignore, но у вас есть .gitignore, npm будет исключать все файлы, определенные в .gitignore

Итак, мы проигнорировали, например, нашу папку dist в нашем .gitignore, потому что мы не хотим, чтобы она была в нашем репо. Теперь нам нужно сообщить npm, что мы хотим включить эти файлы.

Итак, мы добавляем массив files в наш package.json.

"files": [
    "dist"
  ],

Вы также можете быть более откровенным и добавлять только файлы

"files": [
    "dist/my-awesome-lib.js",
    "dist/my-awesome-lib.min.js",
    "dist/my-awesome-lib.esm.js"
  ],

💯 Опубликовать

Теперь мы готовы опубликовать наш пакет. Но поскольку мы разработчики, а разработчики ленивы, мы должны добавить в наши скрипты дополнительную команду. Командный сценарий prepublish.

Этот запускается перед каждым npm publish. Поэтому рекомендуется, например, очистить ваши node_modules и выполнить новую установку зависимостей, выполнить lint и протестировать код, а затем построить код перед публикацией. Но решать вам! 👇🏻

"scripts": {
    "prepublish": "yarn run lint && yarn run test && yarn run build"
  },

И наконец запускаем npm publish. Имейте в виду, что вам нужна учетная запись на npmjs.org;)

🏷 Расст. Теги

Последняя тема очень удобная! Дист-теги. Если вы опубликуете свой пакет, он автоматически получит тег @latest для опубликованной вами версии.

Люди могут установить ваш пакет со строгой версией или с последним тегом: yarn add [email protected] или yarn add my-awesome-package, что эквивалентно my-awesome-package@latest

Теперь есть некоторые обстоятельства, когда вам понадобятся dist-теги. Первый - если вы поддерживаете несколько версий вашего пакета. Хорошими примерами являются webpack, vue и многие другие. Если вы начинаете с v1, а потом работаете над v2.

Допустим, у вас пакет v1.10.0, но вы работаете над выпуском v2.0.0 и хотите, чтобы люди тестировали его, сообщали о проблемах и т. Д.

Проблема в том, что если вы просто npm publish, он получит последний тег. Таким образом, каждый, кто установит его поверх npm install my-lib, получит нестабильную версию 2.0.0, чего мы не хотим. Для этого у нас есть теги. Вы можете перечислить свои теги с помощью npm dist-tag ls, и вы получите список тегов и версий пакетов, присвоенных им.

Теперь вы можете добавить тег к своей команде публикации.

npm publish --tag beta

Таким образом, текущая версия v2.0.0 будет помечена как beta. И тег @latest остается на v1.10.0

Теперь вы можете установить его поверх npm install my-awesome-lib@beta -D

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

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

Вот почему полезно протестировать ваши пакеты перед выпуском с тегом @latest. Для этого вы можете использовать старые добрые кандидаты на выпуск. Потому что, если вы измените версию своего пакета с 2.0.0 на 2.0.1 и опубликуете его с тегом beta, а затем вы увидите, что у вас все еще есть ошибка, вам нужно будет опубликовать следующую версию с 2.0.2. Вы не можете внести изменения в выпуск 2.0.1 и опубликовать его с той же версией с последним тегом.

Вот почему нужны постфиксы релиз-кандидаты или бета.

Вы просто устанавливаете версию в вашем package.json на 2.0.0-rc1 и публикуете ее с тегом beta. Затем вы можете протестировать его и только подтолкнуть rc1 к rc2 и т. Д. Если вы думаете, что готовы к работе, вы публикуете его как 2.0.0 ⭐

Хакерский полдень - это то, с чего хакеры начинают свои дни. Мы часть семьи @AMI. Сейчас мы принимаем заявки и рады обсудить рекламные и спонсорские возможности.

Если вам понравился этот рассказ, мы рекомендуем прочитать наши Последние технические истории и Современные технические истории. До следующего раза не воспринимайте реалии мира как должное!

📦 Как опубликовать свой пакет в npm