Публикация библиотеки в npm — руководство

Создайте простую организацию

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

Чтобы создать организацию, следуйте инструкциям в документации npm.

Создайте токен доступа

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

В этом руководстве используйте упрощенную конфигурацию безопасности:

• Включите параметр Обход двухфакторной аутентификации (2FA).

• Установите для общих разрешений и разрешений организации токена значение Чтение и запись.

Настройте плагин публикации

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

Добавьте плагин в проект Kotlin Multiplatform:

1. Откройте файл build.gradle.kts модуля библиотеки.

2. Добавьте следующую строку в блок plugins {}:

   // <module directory>/build.gradle.kts
   
   plugins {
       kotlin("npm-publish") version "3.7.0"
   }
   

3. Добавьте следующую конфигурацию. Обязательно настройте значения для своей библиотеки. Обязательны только параметры organization, authToken, packageName и version. Остальные приведены в качестве расширенного примера:

   // <module directory>/build.gradle.kts
   npmPublish {
       organization = "organization_name_without_the_@_sign"
   
       registries {
           npmjs {
               // You'll pass your npm token as this environment variable
               // when you run the command to publish the package
               authToken = System.getenv("NPM_TOKEN")
           }
       }
   
       packages {
           named("js") {
               version = "0.0.1"
               packageName = "greetings"
               readme = file("../README.md")
   
               packageJson {
                   license = "Apache 2.0"
                   homepage = "https://github.com/Kotlin/kotlin-multiplatform-web-library#readme"
                   description = "Shared Kotlin/JS Greetings library"
                   keywords = listOf("kotlin", "kotlin-js", "greetings", "shared", "api")
                   author {
                       name = "Kotlin Developer Advocate"
                       url = "https://github.com/kotlin-hands-on/"
                   }
                   contributors = listOf(
                       Person {
                           name = "John Smith"
                           email = "john.smith@example.com"
                           url = "https://github.com/johnsmith"
                       },
                   )
                   repository {
                       type = "git"
                       url = "https://github.com/Kotlin/kotlin-multiplatform-web-library.git"
                   }
               }
           }
       }
   }
   

В блоке npmPublish {} важны следующие параметры:

• Параметр organization и блок registries {} задают данные аутентификации. В данном случае мы используем основной реестр npm и имя переменной NPM_TOKEN, в которой должен храниться токен при запуске задачи публикации.

• Параметры packageName и version задают обязательные параметры пакета:

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

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

• Блок packageJson {} содержит различные метаданные.

Устранение неполадок

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

• Следите за полем version в конфигурации build.gradle.kts: npm не выполнит публикацию, если пакет уже был опубликован с такой же или более ранней версией.

• При создании токена для пакета, относящегося к организации, обязательно настройте как общие разрешения, так и разрешения организации.

Создайте файл рабочего процесса GitHub Actions

Создайте файл .github/workflows/publish.yml с конфигурацией GitHub Action:

# .github/workflows/publish.yml

name: Publish

on:
  release:
    types: [released, prereleased]

permissions:
  id-token: write  # Required for GitHub Actions
                   # to integrate with npm trusted publishing
  contents: read

jobs:
  publish:
    name: Release build and publish
    runs-on: ubuntu-latest
    steps:
      # Check out the triggering branch
      - name: Check out code
        uses: actions/checkout@v4

      # Set up the JDK to run the Gradle task
      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          distribution: 'zulu'
          java-version: 21

      # Run the publishing Gradle task for the library module
      - name: Publish to npm
        run: ./gradlew :shared:publishJsPackageToNpmjsRegistry

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

Настройте GitHub Actions в качестве доверенного издателя

Теперь, когда рабочий процесс опубликован, вы можете использовать GitHub Action, чтобы добавить доверенного издателя для своего пакета npm:

1. Откройте страницу опубликованного пакета.

2. Откройте вкладку Настройки и найдите раздел Доверенный издатель.

3. В разделе Выберите издателя нажмите кнопку GitHub Actions.

4. Заполните форму:

   • имя пользователя GitHub (или организации);

   • имя репозитория;

   • имя файла рабочего процесса (в этом руководстве мы использовали publish.yml).

5. Нажмите кнопку Настроить подключение.

Созданное подключение появится в разделе Доверенные издатели в настройках пакета. Это означает, что рабочий процесс с указанными координатами теперь имеет право публиковать пакеты в npm.

Создайте релиз на GitHub

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

1. Укажите в конфигурации build.gradle.kts версию пакета, которую хотите опубликовать.

2. Перейдите в репозиторий GitHub.

3. На боковой панели справа нажмите Релизы.

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

5. Создайте или выберите тег Git (по возможности укажите версию модуля, чтобы сохранить согласованную нумерацию в разных системах).

6. Укажите название релиза (удобно использовать то же название, что и у тега).

   Чтобы упростить отслеживание, укажите для тега ту же версию, что и номер версии библиотеки, заданный в файле build.gradle.kts.

   

7. Нажмите кнопку Опубликовать релиз.

Чтобы проверить, запустился ли Action, нажмите вкладку Действия в верхней части страницы репозитория GitHub. Вы увидите, что публикация нового релиза запустила рабочий процесс публикации. Нажмите на рабочий процесс, чтобы просмотреть журналы задачи публикации.

После завершения рабочего процесса новая версия пакета должна появиться на странице пакета в реестре npm.