Как опубликовать пакет npm за четыре шага с помощью Webpack и Babel

Вы - младший разработчик, недавно начавший работать в экосистеме JavaScript. Здесь так много всего, что вы даже не представляете, с чего начать. Может попробовать React? Это классная библиотека, надо попробовать. Почему это не работает?

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

Мы будем использовать babel и webpack 4 для доставки компактного и идиоматического кода JavaScript.

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

git clone [email protected]:vmarchesin/how-to-publish-a-npm-package.git

Код разделен на четыре части, и я объясню, где мы находимся в каждой точке. Если вы заблудились, просто прыгайте в следующую ветку, и вы наверняка наверстаете упущенное. В ветви master есть готовый к отправке пакет.

Шаг первый

Во-первых, нам нужно установить наши зависимости. Мы будем использовать babel и webpack, которые я рекомендую для каждого проекта. Вы увидите, что наша библиотека настолько проста, что в этом нет необходимости, но мы делаем это в учебных целях.

Если вы не пользуетесь моим образцом, рекомендуется заранее настроить репозиторий Github для вашего пакета npm. Вы можете узнать, как его создать здесь.

Запустите npm init в каталоге git и следуйте инструкциям. Если вы не знаете, что ввести в поле, просто оставьте его пустым.

Установите все зависимости, запустив:

npm i -D @babel/core babel-loader webpack webpack-cli

npm i - это сокращение для npm install, а -D - сокращение для --save-dev, что означает, что вы сохраните их как зависимости разработчика (они не будут поставляться с вашим кодом).

Также давайте создадим .gitignore файл, чтобы случайно не зафиксировать папку node_modules. Просто добавьте node_modules в .gitignore файл, и все готово.

Хорошая практика - добавить README.md файл, чтобы люди знали, о чем ваша библиотека. Создай.

Если вы хотите перейти к этому моменту, просто проверьте ветку step/one. Если вы сделаете это вместо того, чтобы устанавливать пакеты самостоятельно, не забудьте запустить npm i, чтобы установить все.

Шаг второй

Пришло время написать нашу библиотеку. Давайте реализуем генератор случайных чисел. Назовем его choice в честь Python, хотя он не имеет ничего общего с самим методом Python.

Наша файловая структура должна выглядеть так:

|-src/
| | bool.js
| | float.js
| | index.js
| | integer.js
| .gitignore
| LICENSE
| README.md
| package-lock.json
| package.json

Если у вас нет файла LICENSE, не беспокойтесь. Вы можете скопировать мою и просто изменить копирайт на свое имя. Лицензия MIT - это очень разрешительная лицензия, которая позволяет людям свободно копировать и / или изменять ваш код, если они ссылаются на исходный источник. Вы можете использовать любую лицензию, какую пожелаете.

Код для каждого файла внутри src/ должен выглядеть следующим образом.

Мы экспортируем метод choice, который ожидает аргументы max, min и options. Если мы передадим { float: true } в качестве объекта параметров, мы получим случайное число с плавающей запятой, если мы передадим { bool: true }, мы получим логическое значение, а если мы ничего не передадим, мы получим целое число.

Мы можем использовать синтаксис import и export, потому что мы используем babel. Мы еще не настроили его, но сделаем следующий шаг.

Если вы хотите перейти к этому моменту, просто загляните в ветку step/two.

Шаг третий

Пришло время создать наш пакет. На этом этапе вы можете просто отправить папку src, и она будет работать большую часть времени (наша не будет, потому что мы используем import и export, но вы можете просто изменить на require и module.exports, чтобы она работала). Мы можем добиться большего.

Webpack - это сборщик модулей, а это означает, что он лучше, чем вы, эффективно отправляет код. Он минимизирует и, вместе с загрузчиком babel, перенесет ваш код для экспорта в виде CommonJS модуля. CommonJS определяет формат модуля и делает его читаемым в большинстве сред JavaScript.

Мы поместим конфигурацию нашего веб-пакета в файл с именем webpack.config.js.

Мы только что определили конфигурацию нашего веб-пакета. mode: 'production' позволяет различные улучшения производительности в нашем последнем пакете. entry определяет главный файл в нашем модуле, который является экспортируемым по умолчанию. output определяет, куда будет экспортироваться наш модуль, в данном случае это будет файл dist/index.js. Раздел rules внутри module сообщает webpack использовать babel-loader для всех .js файлов, а раздел resolve там, поэтому нам не нужно добавлять расширение файла в наши import операторы.

Теперь, когда мы настроили webpack, нам нужно сообщить нашему package.json, как собрать наш модуль. Убедитесь, что у вас внутри package.json:

...
"main": "dist/index.js",
"scripts": {
  "build": "webpack --mode production"
},
...

Наш main файл будет вызван, когда мы объявим наш модуль как зависимость. Как видите, это файл, созданный веб-пакетом. Также определите сценарий сборки.

Теперь просто запустите:

npm run build

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

Если вы хотите перейти к этому моменту, просто загляните в ветку step/three.

Шаг четвертый

Мы почти готовы опубликовать наш пакет! Теперь, прежде чем публиковать, нам нужно убедиться, что он работает. Мы можем использовать npm link, чтобы проверить это. npm link Создает виртуальную ссылку на модуль, имитируя npm install.

Следуй этим шагам:

1. Внутри каталога вашего модуля запустите npm link, чтобы создать виртуальную ссылку на этот модуль.
2. Найдите себе проект, над которым вы работаете, и запустите npm link <your_module> в его папке. Обратите внимание: имя вашего модуля не является именем каталога, в котором находится ваш модуль. Это имя, объявленное в вашем package.json файле.
3. Импортируйте / потребуйте ваш модуль внутри вашего проекта и протестируйте его. Он будет рассматриваться, как если бы он был установлен как зависимость.

Если что-то не так, все, что вам нужно сделать, это обновить модуль и снова запустить npm run build. Он автоматически обновит вашу виртуальную ссылку и отразит изменения в вашем проекте, чтобы вы могли ее протестировать.

Когда вы закончите, просто запустите npm unlink внутри каталога модуля и npm unlink <your_module> внутри каталога вашего проекта.

Если все работает, пора публиковать. Краткая версия:

1. Создайте файл .npmignore
2. Создайте аккаунт на npmjs.com (если у вас его нет)
3. Беги npm login
4. Запустите npm publish в каталоге вашего модуля

Давайте разберемся.

Создайте файл .npmignore в корневой папке. Он действует так же, как .gitignore, но сообщает npm, что вы хотите удалить из последнего модуля. Поместите src и webpack.config.js внутрь .npmignore, поскольку мы не хотим, чтобы наш исходный код и конфигурация веб-пакета были связаны с нашим модулем.

Создайте аккаунт на npmjs.com, если у вас его еще нет. Он понадобится вам для публикации модуля под вашей учетной записью. После того, как учетная запись будет готова, запустите npm login на своем компьютере и введите учетные данные.

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

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

Обновление статьи: Вы можете избежать этой проблемы, добавив prepublish скрипт в свой package.json. Это гарантирует, что сборка всегда будет запускаться перед публикацией пакета на случай, если вы забудете собрать его вручную. Просто добавьте сценарий в свой package.json.

...
"scripts": {
  ...
  "prepublish": "npm run build"
},
...

И еще одно: если вы попытаетесь опубликовать свой пакет с тем же именем, что и в этой статье, how-to-publish-a-npm-package, это не сработает. Убедитесь, что имя пакета внутри вашего package.json другое.

Если вы хотите перейти к этому моменту, просто загляните в ветку step/four.

Готово!

Теперь вы можете установить свой модуль в любой проект! Найдите один и попробуйте:

npm i -S <your_package_name>

Вы также можете попробовать этот пакет:

npm i -S how-to-publish-a-npm-package

Вы также можете проверить пакет на npmjs.com:

А теперь иди и опубликуй. Сообщество открытого исходного кода ждет вас.

Вы можете найти меня на моем сайте. Спасибо, что прочитали эту статью.