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

Публикация и восстановление пакетов npm из командной строки

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

Настройка проекта

1. Перейдите к проекту и выберите Артефакты , а затем выберите Подключиться к веб-каналу.
2. Выберите npm на панели навигации слева, а затем следуйте инструкциям в разделе Настройка проекта , чтобы настроить NPMRC-файл и подключиться к веб-каналу. Если вы впервые используете Azure Artifacts с npm на компьютере, убедитесь, что вы выбрали Получить средства , чтобы скачать и установить необходимые компоненты.

Публикация пакетов

1. Откройте окно командной строки и перейдите в каталог, содержащий файл package.json. Если у вас нет файла package.json , выполните следующую команду:

npm init 

npm publish 

Если в вашей организации используется брандмауэр или прокси-сервер, убедитесь, что разрешены URL-адреса и IP-адреса домена Azure Artifacts.

Восстановление пакетов

1. Выполните следующую команду в каталоге проекта, чтобы восстановить пакеты npm:

npm install 

Похожие статьи

• Использование пакетов с сайта npmjs.com
• Публикация пакетов npm с помощью Azure Pipelines (YAML/классическая модель)
• Использование аудита npm

Публикация NPM-пакетов

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

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

Я предпочитаю по возможности брать готовые инструменты, а не изобретать велосипед. Поэтому использую стандартный Create React App . Для поднятия проекта, который будет написан на TypeScript, следует использовать команду:

npx create-react-app my-app --template typescript

Созданный проект будет полностью сконфигурирован для работы с TypeScript.

2. Подготовка структуры проекта

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

src App.css App.tsx index.css index.tsx

Файлы react-app-env.d.ts , reportWebVitals.ts и setupTests.ts не трогаю.

Файлы библиотеки расположим в каталоге src/lib , структура которого будет следующей:

src lib components tests index.css index.ts

Тут все очевидно: компоненты располагаем в components , тесты в tests , точка входа в библиотеку будет в index.ts , стили в index.css .

3. Подготовка package.json

Из коробки Create React App создает минималистичный package.json. Для публикации его необходимо дополнить:

• name — указать реальное название пакета (а не название приложения). Мне лень искать адекватное название в общем пространстве имен, поэтому я использую собственный скоп: @alxgrn/react-form .
• description — описание.
• private — надо поставить в false .
• author — укажем автора, пусть все знают!
• license — указать лицензию. Я выбрал Apache-2.0 . Название надо указывать в правильном формате, если сомневаетесь, потренируйтесь с использованием команды npm init , она умеет проверять.
• keywords — массив ключевых слов для облегчения поиска пакета.
• main и module — точка входа в библиотеку. Мы будем располагать готовые файлы в каталоге dist с точкой входа dist/index.js . Надо отметить что поле module отсутствует в документации, но повсеместно используется. Зачем оно нужно при наличии main — загадка, которую лень разгадывать, поэтому просто напишем и все.
• files — массив файлов, которые будем публиковать. Мы указываем каталог dist , куда сложим готовый проект. По умолчанию также будут добавлены README и LICENSE , причем с любыми расширениями и регистром.
• homepage , repository , bugs — тут все понятно.

ВАЖНО: После того как вы укажете в homepage что-то типа:

"homepage": "https://github.com/alxgrn/react-form#readme",

Ваше тестовое приложение перестанет работать т.к. после сборки будет искать файлы проекта хрен знает где. Для фикса этой неприятности необходимо подправить в секции scripts запуск команды start следующим образом:

"start": "PUBLIC_URL=/ react-scripts start",

4. Установка и настройка babel

Обидно осознавать что Create React App умеет делать все, что нам надо для сборки проекта, но делает это где-то у себя внутри по своим правилам, в которые нас не особо посвящает. Было бы здорово, если бы он умел сразу готовить проект к публикации, но нет, так нет. Будем сами.

Для преобразования TypeScript в JavaScript, который затем перегоним в «древний» JavaScript мы будем использовать babel. Установим его в проект:

npm install --save-dev @babel/cli @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript

Сконфигурируем babel создав в корне файл babel.config.json с следующим содержанием:

 < "comments": false, "presets": [ [ "@babel/preset-env", < "targets": ">0.25%, not dead", "useBuiltIns": "usage", "corejs": "3.6.5" > ], "@babel/preset-react", "@babel/preset-typescript" ], "ignore": [ "**/tests", "**/*.d.ts" ] >

Мы удаляем из результата комментарии, игнорируем файлы тестов (которые будем держать в каталоге src/lib/tests ) и объявления типов (о которых ниже).

Теперь добавим в раздел scripts в файле package.json команду для запуска билда:

"build:js": "rm -rf dist && NODE_ENV=production babel src/lib --out-dir dist --copy-files --extensions \".ts,.tsx\" --source-maps true"

Как уже отмечалось ранее, мы будем складывать результат сборки в каталог dist в корне проекта. Поэтому первое что делает этот скрипт — удаляет предыдущую сборку. Затем он устанавливает переменную среды окружения в продакшен режим и запускает babel. Babel будет искать для обработки файлы с расширениями .ts,.tsx (кроме тех что указали в блоке ignore в файле конфигурации) в каталоге src/lib , а результат записывать в каталог dist . Необработанные файлы будут просто скопированы в dist . Также будут созданы файлы с sourcemap.

5. Генерация файлов объявления типов

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

На предыдущем шаге мы уже сказали babel не обрабатывать эти файлы, а просто скопировать в папку dist . Теперь осталось их сгенерировать. Так как мы использовали Create React App у нас уже есть компилятор tsc, поэтому просто воспользуемся им. Добавим в раздел scripts файла package.json следующую команду:

"build:types": "./node_modules/.bin/tsc --project ./tsconfig.types.json",

Обратите внимание на то, что мы указываем компилятору использовать файл проекта tsconfig.types.json . Мы не можем использовать файл tsconfig.json , который для нас создал Create React App т.к. в нем установлен флаг noEmit , который не совместим с нужным нам флагом emitDeclarationOnly .

Поэтому мы просто копируем файл tsconfig.json в tsconfig.types.json , затем в блоке compilerOptions добавляем «declaration»:true и «emitDeclarationOnly»: true , а «noEmit»: true , наоборот, убираем.

Дополнительно мы меняем в блоке include каталог на src/lib , так как нас интересует только он.

Теперь при запуске команды

npm run build:types

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

6. Добавим команду сборки

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

"build:dist": "npm run build:types && npm run build:js && rm -rf dist/tests",

Дополнительно добавили удаление каталога tests из дистрибутива, т.к. вряд ли он там нужен.

7. Работа с зависимостями

Вернемся к файлу package.json . В нем присутствуют две секции dependencies и devDependencies . В первом перечислены зависимости, которые требуются для работы пакета в продакшене, во втором — только во время разработки.

Это все прекрасно пока мы создаем приложение, но когда мы пишем библиотеку, мы должны учитывать что она будет помещена в целевой проект. В нем скорее всего уже будут установлены зависимости, которые мы тоже используем. Уж точно там будет установлен react коль скоро мы пишем библиотеку react-компонентов. Не обязательно, но возможно, что и другие компоненты тоже уже будут установлены. Если мы оставим эти зависимости внутри своего dependencies , могут возникнуть всякие неприятности типа использования двух реактов в одном приложении. Нам такое не надо. Поэтому я перенес все зависимости из dependencies в devDependencies , а те, которые нам нужны для продакшена в peerDependencies :

"peerDependencies":

Как видите, помимо реакта мне нужен пакет react-children-utilities .

После этих изменений полезно будет запустить

npm install

8. Публикация пакета

Теперь все готово к публикации пакета. Но есть несколько нюансов.

8.1. Я решил использовать в названии пакета имя своего аккаунта т.е. в терминологии npm у меня scoped package . По умолчанию такие пакеты считаются приватными и для их публикации в первый раз надо использовать специальный флаг:

npm publish --access public

В дальнейшем можно запускать команду без этого флага.

8.2. Прежде чем реально публиковать пакет, неплохо было бы его протестировать. Для этого можно использовать команду «npm link» . Но надо быть готовым к тому что всплывет ошибка связанная с Duplicate React.

8.3. Перед очередной публикацией необходимо изменить версию пакета. Можно это делать руками, а можно использовать команду «npm version» .

9. Плюшки

После публикации захочется плюшек.

9.1. Покрытие тестами

Чтобы coverage тестов считался только в каталоге библиотеки, надо добавить в pakage.json настройку для jest :

"jest": < "collectCoverageFrom": [ "src/lib/**/*." ] >

9.2. Беджики в README.md

Беджиков много, их почему-то все любят. Брать можно на shields.io. Для текущей версии и типа лицензии можно взять сразу.

Для беджика прохождения билда можно настроить Action «Node.js CI» на GitHub . В неё же можно сразу добавить интеграцию с codecov.io для вывода беджика покрытия тестами. Codecov , в отличии от Travis CI , не просит вводить данные карты для открытых проектов.

10. Вот и всё

Надеюсь кому-то будет полезно.

Публикация пакета в npm

Представьте ситуацию, что в вашем проекте есть JavaScript-модуль, и нужно скопировать его в другой проект. Есть вариант перенести код вручную, а можно подключить отдельным компонентом, и сделать это всего одной строчкой при помощи npm — менеджера пакетов для Node.js. В этой статье вы узнаете, как оформить ваш модуль в виде пакета, разместить его в общедоступной базе и поддерживать в дальнейшем.

Подготовительный этап

Для создания npm-пакета у вас должен быть установлен Node.js. После установки Node.js с официального сайта, npm в вашей системе появится автоматически.

Убедимся, что npm установлен — проверим его версию, набрав в консоли:

Удобно хранить репозиторий на каком-нибудь хостинге совместной разработки IT-проектов, например, на GitHub. Тогда вы сможете:

• отслеживать историю изменений кода
• получать сообщения пользователей об ошибках

В терминале переместимся в директорию проекта и выполним в ней команду:

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

Package.json

Параметры пакета можно отредактировать напрямую в файле package.json:

• ‘name’— имя, по которому пакет будет доступен в npm
• ‘description’— описание пакета
• ‘author’— никнейм и ссылка на разработчика, например, на гитхабе, либо ‘contributors’— когда в разработке принимало участие несколько человек
• ‘license’ — лицензия

Поля ‘version’, ‘repository’, ‘bugs’, ‘homepage’ будут сгенерированы автоматически при создании package.json.

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

В секцию scripts можно поместить ваши команды, которые должны выполняться Node.js. Например, запуск системы сборки или тестов. Это словарь, заполняемый в формате ключ_команды : выполняемый скрипт.

Чтобы запустить скрипт, достаточно вызвать в консоли:

npm run ключ_команды

При запуске npm run build будет выполнено: webpack —progress —display-error-details —display-entrypoints —display-reasons

Добавление скриптов позволит вам вызывать серию команд по одному ключевому слову.

Здесь перечислены основные поля package.json. Как работать с остальными, можно почитать в официальной документации.

README

Осталось оформить файл пользовательской документации или README.md, поясняющий, как установить и настроить ваш модуль. Если у вас не было опыта написания README, то об основных правилах можно почитать по ссылке. А если ищете готовый шаблон, то вот один из вариантов. Теперь можно приступать к самому интересному — публикации пакета в npm.

Публикация в npm

Если вы не зарегистрированы на npmjs.com — сделайте это с помощью команды:

npm adduser

Если же у вас есть учётная запись — вы можете авторизоваться:

Вас попросят ввести логин и пароль.

После ввода следующей команды ваш пакет окажется в npm, поэтому важно ещё раз всё проверить и убедиться в работоспособности модуля. Проверили? Отлично, публикуем 🙂

Наберите в консоли:

npm publish

Если публикация прошла успешно, можно перейти по ссылке и увидеть информацию о пакете:

https://npmjs.com/package/<your_package_name>

Также он появится у вас в профиле на сайте.

Публикация от имени команды

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

Обратите внимание: пакеты, публикуемые от имени команды, по умолчанию private. Чтобы сделать ваш пакет общедоступным, выполните публикацию с ключом —access public:

npm publish —access public

Установка пакета

Наконец, когда пакет опубликован, его можно установить и подключить в любом проекте с помощью команды:

npm install mypackage

В JavaScript-файле, где вы хотите использовать модуль, пропишите:

import mypackage from ‘mypackage’;

Готово, теперь вы можете обращаться к модулю по имени. Например, для вызова метода init:

mypackage.init();

Обновление пакета

Что нужно сделать, чтобы обновить модуль?

1. Внести изменения в код.
2. Обновить версию: npm version [ major | minor | patch ]
3. В терминале ввести npm publish

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

Если изменения незначительные (исправления мелких ошибок) — npm version patch. Это увеличит версию package.json, например, с 1.0.0 до 1.0.1

Если в пакете появились новые методы, не влияющие на уже существующие, то npm version minor и изменение второго знака: 1.0.0 —> 1.1.0

В случае модификации кода без обратной совместимости с предыдущей версией, npm version major — то, что вам нужно. И увеличение версии: 1.0.0 —> 2.0.0

Если сомневаетесь, какую из трех команд использовать, почитайте об этом здесь.

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

Удаление пакетов из npm

Начнем с того, что удаление пакетов считается плохой практикой — от них могут зависеть проекты других пользователей. Однако, если вы опубликовали пакет командой npm publish, и поняли, что что-то пошло не так, отменить это действие в течение 24 часов можно командой npm unpublish. Npm запретил самостоятельно удалять пакеты, которые старше суток.

Если удалить такой пакет всё же необходимо, напишите в поддержку, указав причину. Пакет будет помечен как @deprecated и исчезнет из вашего профиля. Npm предупреждает о невозможности публикации нового пакета, если его название и версия будут совпадать с удаленным. Но есть и хорошие новости — пакет можно опубликовать повторно, изменив номер версии 🙂

Итого

Публикация в npm позволяет подключать модули отдельными компонентами. А семантическое версионирование пакетов помогает пользователям понимать совместимость релизов друг с другом.

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

1. Небольшой видео-гайд по публикации в npm
2. Как собрать пакет npm

If you like this article, share a link with your friends

Read more

We talk about interesting technologies and share our experience of using them.

Создание и публикация пакетов private

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

1. Если вы используете npmrc для manage accounts on multiple registries , в командной строке переключитесь на соответствующий профиль:

npmrc profile-name>

mkdir my-test-package

cd my-test-package

git init git remote add origin git://git-remote-url

npm init --scope=@my-org

npm init --scope=@my-username