Оглавление

  1. Прелюдия
  2. Создадим библиотеку
  3. Вызовы на пути
  4. Настройка проекта
  5. Создание семантической версии набора изменений
  6. Построение конвейеров развертывания библиотек
  7. Создание токена Npm и предоставление всех необходимых разрешений
  8. Первоначальная публикация в NPM
  9. Конвейер развертывания в действии
  10. Спасибо, что пришли и увидимся в следующем
  11. Бесстыдная самореклама 😈

Весь код, написанный в этой статье, можно найти здесь

Прелюдия

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

Просто с помощью команды npm install узел может загрузить чужой код на мою машину 🤯 и не только. При изменении версии с помощью npm update или ручном изменении номера в package.json и повторном выполнении npm install устанавливается другая версия кода!

Когда мы командуем + щелкаем по импортированной переменной/функции, она переходит к коду библиотеки. Иногда этот код хорошо организован, а иногда — полный спагетти.

И как все это работает?

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

Давайте создадим библиотеку

Проблемы на пути

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

Во-первых, у нас есть чувство собственного достоинства. Поэтому мы пойдем с TypeScript!

Мы хотим, чтобы наши пользователи имели безопасность типов наших функций.

TypeScript означает проблемы, у нас будет этап сборки, и мы создадим 3 разных формата файлов.

  • .d.ts (для файлов типов (ваши пользователи увидят содержимое этого файла, когда перейдут к вашим функциям))
  • .js (скомпилированный JS-код, который будет выполняться при сборке проекта пользователями)
  • .mjs (намного более удобочитаемая версия .js файлов (построена для node))

Благодаря отличной экосистеме JS у нас есть несколько отличных решений для решения сложных задач. Замечательная библиотека под названием tsup позаботится о создании файлов для нас.

Это еще не все, у нас также будет проблема с семантическим версионированием. Мы хотим разделить изменения patch, minor и major. Также мы хотим регистрировать каждое из этих изменений в своего рода журнале изменений, чтобы наши пользователи могли читать то, что мы добавляем в более новых версиях.

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

  • семантическое версионирование,
  • обновление списка изменений
  • конвейер автоматического развертывания

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

Вау, у нас много работы, давайте начнем прямо сейчас!

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

Начнем с создания нового проекта npm. Достойный.

$ mkdir dummy-lib
$ cd dummy-lib
$ npm init -y

В этой фиктивной библиотеке мы создадим несколько полезных функций, чтобы люди могли легко вычислять, является ли число четным или нечетным, потому что почему бы и нет?

Мы создадим папку index.ts в каталоге src

источник/index.ts

Также, пожалуйста, добавьте файл atsconfig.

tsc --init

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

Добавим для этого tsup

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

pnpm install tsup

После установки мы добавим скрипт build с дополнительными данными package.json.

Теперь, когда мы бежим

pnpm run build

Мы ожидаем увидеть несколько файлов в каталоге dist

Эти файлы объявлений содержат все типы с Javadoc. Когда ваши пользователи нажимают на ваши функции, они переходят к этим файлам объявлений 👍

Создание семантического управления версиями набора изменений

Всякий раз, когда мы что-то меняем в коде. Это изменение на patch, minor или major. Каждый раз, когда мы вносим изменения, нам нужно добавить файл changeset в наш обновленный код и описать, в чем заключалось изменение.

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

pnpm install -D @changesets/cli && npx changeset init

Этот создает каталог .changeset, в котором будут храниться наши настройки набора изменений.

Вам нужно обновить .changeset/config.json, чтобы разрешить публичный доступ (очевидно, если это общедоступная библиотека), и вы должны указать базовую ветку для вашей библиотеки (позднее набор изменений будет использовать эту ветку для создания запросов на включение, но об этом позже).

Мой конфиг changeset выглядит так

Время добавить первоначальный набор изменений

npx changeset

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

Он создает новый файл в каталоге .changeset. Позже, когда мы создадим действие GitHub для конвейеров развертывания, действие changeset рассмотрит эти файлы и на основе содержимого либо создаст запрос на извлечение с изменением версии, либо напрямую отправит изменения в npm.

Построение конвейеров развертывания библиотек

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

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

У нас будет 2 файла рабочего процесса: основной и выпуск.

main будет обрабатывать то, что происходит, когда кто-то делает запрос на вытягивание (запуск тестов, запуск lints, сборка машинописного текста и т. д.).

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

  1. Создайте новый запрос на изменение версии нашей библиотеки или
  2. Он напрямую отправит новую версию нашей библиотеки в npm.

Вот блок-схема, которая упрощает весь процесс развертывания новой версии нашей библиотеки.

Ладно, хватит теории, покажи код.

Мы начнем с основного файла рабочего процесса

.github/workflows/main.yml

В этом рабочем процессе мы можем выполнять базовые проверки запроса на вытягивание.

Что важнее, так это рабочий процесс release. Если он найдет файл changeset, то создаст пулреквест в нашу базовую ветку (для нас основную).

Если он не находит файл набора изменений, а измененную версию в package.json (когда набор изменений создает PR, он также изменяет версию в package.json), то он отправляет новую версию в npm и обновляет CHANGELOG.md

Вы можете видеть, что в качестве последнего шага нашего Release job мы запускаем changesets/action@v1 и указываем pnpm run release в опции публикации.

Но мы еще не создали этот скрипт. Время написать сценарий выпуска для package.json

Когда набор изменений выполняет команду changeset publish, он использует команду npm publish <package-spec> за кулисами.

Он также включает параметры публикации, которые мы указали в .changeset/config.

Ладно, Барис, вроде все нормально, но что это за npm token, GitHub token и т.д.

Эти жетоны, друг мой, будут рассмотрены в следующем разделе.

Создание токена Npm и предоставление всех необходимых разрешений

Npm не глуп, вы не можете просто пойти и опубликовать следующую версию reactjs. Он имеет защиту, основанную на необходимых разрешениях.

Npm принимает токены, либо токены 2FA, либо классические токены.

Если бы вы сказали мне, что вы опубликуете свою библиотеку вручную. Я определенно рекомендую вам использовать токен 2FA.

Но действие GitHub не может прочитать токен в вашем приложении для проверки подлинности. Поэтому приходится использовать классические токены.

Нам нужно войти в npm и создать новый токен.

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

После создания токена сохраните его в безопасном месте.

Теперь нам нужно перейти в настройки нашего репозитория, а оттуда в секреты действий GitHub.

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

Это не все. Мы также должны разрешить действиям GitHub фактически создавать для нас запрос на вытягивание. Для этого у нас есть еще одна опция в настройках.

Хорошо, переменная NPM_TOKEN env настроена и готова. А GITHUB_TOKEN?

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

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

Первоначальная публикация в NPM

Прежде чем мы протестируем наш прекрасный автоматический конвейер, нам нужно сделать еще один шаг. Нам нужно создать пакет npm. И единственный способ сделать это — опубликовать библиотеку вручную.

Итак, давайте сделаем это

npm login

npm publish

Если вам повезет, вы увидите свой пакет на npm 😄.

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

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

Конвейер развертывания в действии

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

git checkout -b feature/testing-changeset

внесите некоторые фиктивные изменения и добавьте набор изменений

npx changeset

Затем зафиксируйте и нажмите

git add .
git commit -m "feature/testing-changeset: test"
git push -u origin feature/testing-changeset

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

Настройка бота набора изменений не требует усилий, вам просто нужно перейти к боту набора изменений и нажать Настроить.

Теперь мы готовы, давайте создадим PR!

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

Давайте одобрим PR и посмотрим, что произойдет.

Он выполнил рабочий процесс выпуска в действиях GitHub.

После этого был создан новый PR!

Этот PR был создан ботом набора изменений, давайте посмотрим, что он пытается изменить.

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

Когда мы одобряем этот PR, мы видим, что он снова запускает рабочий процесс выпуска, и на этот раз он публикует эти изменения в npm.

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

Спасибо, что пришли и увидимся на следующем

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

И так, чего же ты ждешь! Просто начните писать свою новую убойную библиотеку 😄

Бессовестная самореклама 😈

Эй, если этот контент был для вас полезен, не забудьте поставить лайк и прокомментировать.
Давайте оставаться на связи, чтобы получать больше подобного контента.
Пожалуйста, подпишитесь на Medium и другие каналы (особенно Twitter 😄)

Twitter 🐦
Linkedin 📎
Github 👨🏻‍💻
Medium 📰
Dev.to 🤖

Дополнительные материалы на PlainEnglish.io.

Подпишитесь на нашу бесплатную еженедельную рассылку новостей. Подпишитесь на нас в Twitter, LinkedIn, YouTube и Discord .