Автоматизируем публикацию npm-пакета с помощью Github Actions

Не так давно я выпустил npm-пакет @baranov-guru/react-telegram-widgets и решил поделиться своим опытом по автоматизации сборки и публикации обновлений пакета.

В начале статьи дана небольшая справка, о том что такое NPM и Github Actions.

💡 Если вам интересно сразу готовое решение, жмите сюда.

Что такое NPM?

NPM (Node Package Manager) — это менеджер пакетов для JavaScript. Проще говоря - это программа, которая помогает устанавливать и управлять чужими библиотеками (частями кода), и использовать их в своём JavaScript-проекте.

Она идёт в комплекте с Node.js и позволяет:

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

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

Что такое Github Actions?

GitHub Actions — это инструмент внутри GitHub, который предоставляет инструменты для непрерывной интеграции и непрерывной поставки (CI/CD). Или если проще, то помогает автоматически выполнять задачи с вашим кодом:

• собирать проект,
• проверять, работает ли код (прогонять тесты),
• выкладывать его на сервер или в облако.

Всё это происходит автоматически, по заранее созданным правилам, описанным в workflow файлах. Это удобно, потому что не нужно делать всё вручную.

Собираем свой Github workflow

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

Нас интересует два момента:

• Когда запускать workflow?;
• Как публиковать в npm;

Когда запускать workflow?

Для себя я выбрал следующую схему работы:

• Все изменения вливаются в main ветку проекта;
• Публикация же в npm происходит после ручного создания Github Release.

Для этого надо добавить следующий код в workflow:

on:
  release:
    types: [published]

Если же вы хотите публиковаться каждый раз при добавлении коммита в main ветку, то надо прописать следующее:

on:
  push:
    branches: [main]

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

Тут всё просто, необходимо использовать команду:

npm publish

Шаг в workflow может выглядеть следующим образом:

- name: Publish to npm
  run: npm publish

Однако, если запустить такой workflow, то он упадёт с ошибкой авторизации, при публикации пакета.

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

Для этого необходимо добавить токен.

Получение токена

Получить токен можно в личном кабинете NPM.

Для этого надо:

• перейти на страницу с токенами;

• затем создать токен, нажав на кнопку "Generate New Token";

Для простых целей, нам хватит классического legacy access token. Его и выберем:

• заполнить форму и скопировать полученный токен;

Так как мы собираемся публиковаться через Github Actions, то выбираем тип токена "Automation".

Полученный токен необходимо добавить в repository secrets в репозитории проекта на github.

Добавление токена в Secrets на Github

Нам необходимо создать секрет NPM_TOKEN. Для этого необходимо:

• перейти в настройки репозитория;
• развернуть вкладку Secrets And Variables;
• выбрать Actions;

На открывшейся странице нажать кнопку New Repository Secret и вставить в модальном окне полученный ранее токен

Теперь осталось только указать токен в переменной окружения NODE_AUTH_TOKEN в нашем workflow:

- name: Publish to npm
  run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Особенности публикации @scoped пакетов

Если у вас, как и у меня, scoped package, то по умолчанию пакет не будет публично доступен.

Для решиния этой проблемы необходимо добавить параметр access со значением public.

npm publish --access public

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

Происхождение публикуемых пакетов (Provenance)

Так же, Github Actions из коробки позволяют создавать сведения о происхождении публикуемых пакетов (Provenance).

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

npm publish --provenance

Однако, если запустить такой workflow, то мы увидим следующую ошибку:

npm error code EUSAGE
npm error Provenance generation in GitHub Actions requires "write" access to the "id-token" permission

Как и написано в ошибке, необходимо добавить в workflow пермиссию id-token со значением write. Выглядит она следующим образом:

permissions:
  id-token: write
  contents: read

Теперь, если вы всё сделали правильно, в опубликоманном пакете можно будет увидеть следующую плашку:

Итоговый workflow

# Название workflow
name: Publish Package

# Когда выполнять
on:
  release:
    types: [published]

# Работа с разрешениями
permissions:
  id-token: write
  contents: read

# Описание job
jobs:
  build-and-publish:
    runs-on: ubuntu-latest

    steps:
      # Получение актуального кода проекта
      - name: Checkout code
        uses: actions/checkout@v4

      # Настройка окружения
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"
          registry-url: "https://registry.npmjs.org"
          cache: "npm"

      # Опционально: Установка зависимостей, линтинг, прогон тестов
      # ...

      # Сборка пакета
      - name: Build package
        run: npm run build

      # Публикация пакета
      - name: Publish to npm
        run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}