Как сделать свой npm пакет
Локальный NPM репозиторий за 5 минут со своими пакетами и кэширование
Доброго времени суток!
Рано или поздно в организациях возникают проблемы с распространением js модулей между проектами, настало то время когда в нашей компании встал этот вопрос.
Копировать и вставлять код это путь на темную сторону, поэтому было принято решение писать не просто js код, а создавать из него npm пакеты чтобы распространять между своими проектами.
Поиск бесплатных, частных npm репозиториев завел в тупик, а использование частных репозиториев на npm требует платы (а это не наш менталитет).
Поскольку в офисе есть сервер, который работает всегда(почти), было решено развернуть локальный npm.
Устройство популярных локальных npm репозиториев достаточно простое и однообразное, мы выбрали Verdaccio, из-за того, что обновления для него публиковались сравнительно недавно.
В основном это npm пакет, который ставится на Node.js > 4 и предоставляет веб интерфейс на определенный порт.
Огромным плюсом является функция кеширования, когда локальный npm не находит запрошенный у него пакет, то он идет на npmjs.com, скачивает к себе на диск нужный пакет и при повторных запросах этого пакета раздает его уже кешированную версию.
На машине, которая будет сервером:
В файле C:\Users\lab\AppData\Roaming\verdaccio\config.yaml находятся параметры сервера
Параметры по умолчанию жизнеспособны, можно ничего не менять, достаточно в конце файла дописать настройку, благодаря которой Verdaccio будет понимать какой порт прослушивать.
192.168.51.79 это ip сервера, задав адрес таким образом мы сможем обращаться из локальной сети по ip сервера, либо по его DNS имени и добавив порт 1234 мы будем попадать на web интерфейс.
Если прописать listen: 192.168.51.79:80 то писать порт при настройках клиентов необязательно.
Далее запускаем наш локальный npm
Остальные действия будем производить на клиентах.
Устанавливаем путь к локальному репозиторию.
Готово, теперь все Ваши npm запросы будут идти и кешироваться через локальный сервер.
Если Вам нужно опубликовать npm пакет на сервер, то выполняем следующую инструкцию.
Проверяем, что мы под пользователем «login»
Публикуем пакет, rootProjectFolder — это папка с минимум тремя файлами index.js \ package.json \ README.md, пример выложил на github.
Обновляем пакет. Обновляем версию в package.json, выполняем команды
Пакет на локальном сервере, можно перейти на 192.168.51.79:1234 и посмотреть, что там появился новый пакет.
Кстати, информация о каждом из пакетов представлена в удобном виде и есть поиск по локальным пакетам.
P.S.: Если Вы ваша сеть имеет прокси, то на сервере нужно явно указать ее параметры, а на клиенте этого делать не нужно, потому что npm репозиторий локальный и для доступа клиентов к серверу прокси не требуется.
На сервере надо выполнить команду npm config edit и добавить следующие строчки
P.P.S. При запуске на windows, предпочтительнее пользоваться powershell на сервере, в cmd npm может зависнуть через сутки.
Буду рад комментариям и отзывам о том, как это устроено у вас.
Как опубликовать собственный NPM-пакет
Хочешь проверить свои знания по JS?
Подпишись на наш канал с тестами по JS в Telegram!
Перевод статьи «Publish your own NPM package».
Название статьи может показаться пугающим. Для меня самого так и было. Но я покажу вам, что бояться здесь нечего. Опубликовать свой первый NPM-проект — просто интересный опыт.
Если вас в принципе заинтересовала эта статья, значит, вы по крайней мере слыхали об NPM и, вероятно, пользовались им ранее.
Просто короткое напоминание: NPM — это самый крупный реестр программного обеспечения, а также менеджер пакетов и установщик.
Хотите узнать, как установить NPM? Собственно, он поставляется в комплекте с Node. Если хотите узнать, как установить Node, загляните на Homebrew.
Для чего вам может понадобиться публиковать NPM-пакет?
Допустим, вы создали что-то, чем сами постоянно пользуетесь в своих проектах. Тогда, вероятно, вы уже поняли, какая это головная боль — обновлять этот код повсюду. А вот если вы опубликуете этот код в виде NPM-пакета, вы сможете вносить изменения во все свои проекты, где он используется, при помощи команды npm-update.
Вторая причина опубликовать свой пакет — если вы думаете, что созданный вам код может быть полезен и другим людям. Руководствуясь именно этой причиной, я создал свой первый публичный компонент Astro.
Как создать собственный NPM-пакет
Начнем с самого начала.
Сперва создадим нашу локальную папку.
Затем инициализируем NPM.
По ходу дела отвечайте на вопросы, которые будут появляться на экране.
Пишем код
Теперь давайте создадим какой-то код, чтобы наш плагин что-то делал.
Сделаем суперпростой пример: код в нашем пакете будет всего лишь выполнять базовые математические действия.
Создаем файл index.js и добавляем в него следующий код:
Поскольку мы хотим использовать этот пакет в дальнейшем, мы можем затребовать функцию add :
Добавление нескольких функций
Конечно, если наш плагин будет просто складывать числа, он будет практически бесполезен. Давайте добавим еще несколько функций и посмотрим, как их можно будет экспортировать и использовать.
После загрузки нашего пакета мы сможем импортировать эти функции:
Добавление README
Добавлять README-файл в свои проекты — хорошая привычка. Этот текст может быть сколь угодно подробным, но как минимум он должен включать:
Тестируем наш пакет
Включить в пакет тесты — всегда хорошая идея. Благодаря этому вы всегда сможете легко проверить, работает ли ваш код, когда внесете в него какие-либо изменения.
Не буду вдаваться в детали относительно кода тестов, это отдельная тема. Но самый базовый тест, который мы можем сделать, — ручной.
Мы можем протестировать наш пакет даже до того, как он будет опубликован в NPM-реестре. Для этого нужно подключить его локально.
Перейдите в папку пакета и выполните следующую команду:
В проекте, в котором хотите попробовать использовать свой пакет, выполните команду:
Если все работает хорошо, переходим к следующему шагу.
Публикация NPM-пакета
Прежде чем публиковать пакеты в NPM-реестре, нужно завести себе аккаунт на сайте NPM.
Когда у вас будет аккаунт, вы сможете запустить в своем терминале команду:
Следуйте шагам, которые будет предлагать скрипт.
Когда все будет готово, в том числе и код, который вы хотите опубликовать, введите команду:
Вы использовали в имени пакета свое имя ( @username/my-package )? Тогда вы получите сообщение, что такие пакеты бесплатно не публикуются.
Таким образом, нам нужно опубликовать этот пакет как публичный:
А теперь вы можете зайти на npmjs и посмотреть, что получилось.
Обновление вашего пакета
Что касается обновлений, при необходимости вы всегда можете обновить ваш код. Следующий шаг после этого — обновить версию пакета.
Наилучший подход — использовать семантическую нумерацию версий. Это предполагает обозначение версии тремя цифрами через точку.
Цифры в номере версии говорят следующее:
Почитать больше на эту тему можно на сайте semver.
Обновив версию, вы можете ее опубликовать, как делали ранее:
Заключение
Вот и все. Теперь у вас есть ваш собственный пакет в реестре NPM!
Следите за сообщениями о проблемах, которые будут отсылать люди, использующие ваш пакет. Также не забывайте уделять внимание вопросам безопасности.
Как опубликовать пакет в NPM
Подробная инструкция по публикации, обновлению, удалению и установке ваших пакетов в Node Package Manager.
Оглавление
Для начала нужно ответить на вопрос — зачем вам вообще использовать NPM? Ответ очень просто, вы можете написать некий плагин, компонент или скрипт и таскать его из проекта в проект. Если вдруг вы обнаружите ошибку или захотите улучшить ваше творение, вам придется во всех проектах ручками править код. Этого можно избежать, добавив ваше творение как отдельный пакет в NPM и подключать / обновлять его одной командой на всех ваших проектах.
Что нужно для работы с NPM?
Чтобы создать NPM-пакет у вас должен быть установлен Node.js. После установки Node.js, нужно убедиться что установка прошла корректно и заодно проверить его версию, сделать это можно следующей командой:
Инициализация NPM-пакета
Перед тем как инициализировать NPM-пакет важно отметить, что для его грамотной и удобной разработки, лучше всего использовать какой-нибудь Git-репозиторий, например Github или Gitlab. Теперь в терминале, находясь в директории вашего NPM-пакета, нужно провести его инициализацию выполнив следующую команду:
package.json
Вы можете редактировать файл package.json вручную. Вот основные и самые важные его настройки:
Перед тем как создавать пакет, убедитесь что такого названия в базе NPM еще нету. Для этого воспользуйтесь поиском на сайте, вбейте название которое придумали и проверье уникальность.
README.md
После инициализация проекта, правилом хорошего тона будет создание документации по установке и использованию вашего проекта. В корне создайте файл README.md и пропишите все что может быть полезно другим разработчикам (да и вам) по управлению вашим проектом.
Пример README.md можете взять отсюда.
Публикация NPM-пакета
Для начала нужно пройти регистрацию на npmjs.com, сделать это можно из терминала командой:
Если же учетная запись у вас уже есть, то нужно авторизироваться в терминале:
Проверить под какой учетной записью вы находитесь можно с помощью команды:
Теперь можно публиковать NPM-пакет:
После введения команды выше, ваш пакет отправиться на сервера NPM и будет доступен для подключения к проектам.
Обновление NPM-пакета
Без обновлений никуда. Для того чтобы правильно обновить пакет, вам нужно:
Правильное версионирование пакета поможет разработчикам, которые используют ваш пакет понять, насколько критические изменения были внесены.
npm version patch
npm version minor
npm version major
Удаление NPM-пакета
Если все-таки вам необходимо удалить пакета, то напишите в поддержку, указав причину удаления пакета. Пакет будет помечен как @deprecated и исчезнет из вашего профиля.
Установка NPM-пакета
После того, как ваш NPM-пакет появился в вашем профиле, он будет доступен по ссылку:
И его можно будет подключить к любому вашему проекту, с помощью команды:
Теперь, вы можете гибко обновлять код вашего компонента, без необходимости вручную вносить изменения на уже существующих проектах. Просто обновите пакет до актуальной версии и все изменения подтянуться автоматически.
Благодарность автору
Если по какой-либо причине вы хотите поблагодарить автора данного ресурса, вы можете это сделать одним из удобных для вас способов ниже.
Один из самых популярных способов поблагодарить автора, воспользоваться сервисом Яндекс.Деньги.
Как собрать пакет npm
NPM — пакетный менеджер JavaScript. Он управляет зависимостями как для клиентской стороны, так и для серверной. Если вы намерены выложить исходный код своего проекта и иметь возможность устанавливать его как отдельный компонент, лучший способ сделать это — создать пакет.
Что для этого нужно?
Для начала установить пакетный менеджер, если это ещё не было сделано. Установка зависит от используемой вами операционной системы, описывать её не вижу смысла: материала по этому вопросу предостаточно.
Акканут
Первый шаг самый тривиальный. Зарегистрируйтесь на npmjs.com. После этого вы сможете публиковать пакеты от своего имени прямо из командной строки. Введите команду:
Подготовка проекта к публикации
Помимо самого кода, обязательно приложить файл README.md, содержащий описание того как подключить и использовать пакет.
Осталось только закоммитить изменения и выложить код на github.
Тестируем пакет
Всегда тестируйте работоспособность своего творения прежде, чем публиковать его в репозиторий npm.
Публикация
ES6-модули
Допустим, нужно использовать не commonJS, а модули ES6. Что тогда? Увы, нам не обойтись без транспайлера Babel.JS. Именно с его помощью будут проводиться все манипуляции. Ставим необходимые пакеты как зависимости нашей библиотеки.
Также надо создать два каталога: один для исходников, другой — для скомпилированной версии скрипта. Это будут src и lib соответственно.
Для удобства пропишите нужные команды в package.json своего проекта.
Таким образом, в git находятся только исходники, а при публикации в npm будут собраны и файлы, пропущенные через транспайлер.
Для подключения модуля в конкретном проекте теперь можно установить его стандартным способом и импортировать.
Creating and publishing private packages
To share your code with a limited set of users or teams, you can publish private user-scoped or organization-scoped packages to the npm registry.
For more information on scopes and private packages, see «About scopes» and «About private packages».
Note: Before you can publish private user-scoped npm packages, you must sign up for a paid npm user account.
Additionally, to publish private organization-scoped packages, you must create an npm user account, then create a paid npm organization.
Creating a private package
If you are using npmrc to manage accounts on multiple registries, on the command line, switch to the appropriate profile:
On the command line, create a directory for your package:
Navigate to the root directory of your package:
If you are using git to manage your package code, in the package root directory, run the following commands, replacing git-remote-url with the git remote URL for your package:
In the package root directory, run the npm init command and pass the scope to the scope flag:
For an organization-scoped package, replace my-org with the name of your organization:
For a user-scoped package, replace my-username with your username:
Respond to the prompts to generate a package.json file. For help naming your package, see «Package name guidelines».
Create a README file that explains what your package code is and how to use it.
In your preferred text editor, write the code for your package.
Reviewing package contents for sensitive or unnecessary information
Publishing sensitive information to the registry can harm your users, compromise your development infrastructure, be expensive to fix, and put you at risk of legal action. We strongly recommend removing sensitive information, such as private keys, passwords, [personally identifiable information][pii] (PII), and credit card data before publishing your package to the registry. Even if your package is private, sensitive information can be exposed if the package is made public or downloaded to a computer that can be accessed by more users than intended.
Testing your package
To reduce the chances of publishing bugs, we recommend testing your package before publishing it to the npm registry. To test your package, run npm install with the full path to your package directory:
Publishing private packages
By default, scoped packages are published with private visibility.
On the command line, navigate to the root directory of your package.
To publish your private package to the npm registry, run:
To see your private package page, visit https://npmjs.com/package/*package-name, replacing package-name* with the name of your package. Private packages will say private below the package name on the npm website.
For more information on the publish command, see the CLI documentation.