ライブラリをnpmに公開する – チュートリアル
npm-publish Gradle プラグインを使用して、Kotlin Multiplatformライブラリを手動またはGitHub Actionsを使ってnpmに公開します。
ライブラリを公開するには、以下の手順が必要です。
- npmのアカウントやアクセストークンなどの認証情報を準備する。
- Kotlin Multiplatformプロジェクトで公開プラグインを設定する。
- 公開プラグインに認証情報を提供するか、継続的インテグレーション(CI)用のTrusted Publisherを設定する。
- 手動またはCIを使用して公開タスクを実行する。
このチュートリアルでは、プロジェクトのホスティングにGitHubを使用し、GitHub Actions経由でCIを実行します。
サンプルライブラリ
実際の動作する設定を確認しながら進めるために、サンプルライブラリプロジェクトを利用できます。
コードを再利用する場合は、すべてのサンプル値を実際のプロジェクトに応じた値に置き換えてください。
アカウントと認証情報の準備
npmに公開するには、npmポータルにサインインしている必要があります。
このチュートリアルでは、手動公開を設定するためにOrganization(組織)とアクセストークンが必要です。
シンプルなOrganizationの作成
このチュートリアルでは、名前の衝突を避けるためにnpmのOrganization配下にライブラリを公開します。
新しいOrganizationを作成するには、npmのドキュメントに従ってください。
アクセストークンの生成
手動でnpmに公開するには、新しく作成したOrganization配下にパッケージを公開できるアクセストークンが必要です。 トークンを生成するには、npmのガイドに従ってください。
このチュートリアルでは、簡略化したセキュリティ設定を使用します。
- Bypass two-factor authentication (2FA) オプションを有効にします。
- トークンの全般的な権限(general permissions)とOrganizationの権限の両方を Read and write に設定します。
ライブラリプロジェクトの設定
サンプルプロジェクトを使用する場合は、公開前にデフォルトの名前を更新してください。 これには以下が含まれます。
- ライブラリモジュールの名前
settings.gradle.ktsファイルで設定されているプロジェクト名
名前を設定したら、次の手順に従って公開の設定を行います。
公開プラグインの設定
このチュートリアルでは、npmへの公開を支援する公式の npm-publish プラグイン を使用します。 プラグインの詳細や利用可能な設定オプションについては、プラグインのドキュメントを参照してください。
Kotlin Multiplatformプロジェクトにプラグインを追加します。
ライブラリモジュールの
build.gradle.ktsファイルを開きます。plugins {}ブロックに次の行を追加します。kotlin// <module directory>/build.gradle.kts plugins { kotlin("npm-publish") version "3.7.0" }プラグインの最新バージョンについては、Releases ページを確認してください。
次の設定を追加します。 ライブラリに応じた値にカスタマイズしてください。 必須のパラメータは
organization、authToken、packageName、versionのみです。 残りは拡張例として記載しています。kotlin// <module directory>/build.gradle.kts npmPublish { organization = "organization_name_without_the_@_sign" registries { npmjs { // パッケージを公開するコマンドを実行する際、 // この環境変数としてnpmトークンを渡します 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" } } } } }これを設定するために、Gradleプロパティを使用することもできます。
npmPublish {} ブロックの重要な設定は以下のとおりです。
organizationパラメータとregistries {}ブロックで認証の詳細を指定します。 ここではメインのnpmレジストリと、公開タスク実行時にトークンを保持するNPM_TOKEN環境変数の名前を使用します。packageNameパラメータとversionパラメータは、必須のパッケージオプションを定義します。versionパラメータは省略可能で、省略した場合はモジュールのバージョンがデフォルト値として使用されます。packageNameパラメータは省略可能で、省略した場合はモジュール名がデフォルト値として使用されます。
packageJson {}ブロックには各種メタデータを指定します。
手動での公開
手動公開は、プロジェクト構造を試行錯誤している段階や、公開の自動化を独自に実装したい場合に役立ちます。
これでローカルマシンからライブラリをnpmに公開できるようになりました。 公開するには、YOUR_ACCESS_TOKEN の部分に先ほど生成したアクセストークンを貼り付けて、次のコマンドを実行します。
NPM_TOKEN=YOUR_ACCESS_TOKEN ./gradlew :shared:publishJsPackageToNpmjsRegistryライブラリが公開されると、npmレジストリで確認できるようになります。 npmのOrganizationページを開き、(個人の Packages ページではなく)Packages タブを確認してください。

トラブルシューティング
手動公開でよく発生する問題には、以下のようなものがあります。
build.gradle.kts設定内のversionフィールドに注意してください。 すでに同じバージョンまたはそれ以前のバージョンでパッケージが公開されている場合、npmは公開を失敗させます。- Organizationスコープのパッケージ用にトークンを生成する際は、全般的な権限(general permissions)および Organizationの権限の両方を設定していることを確認してください。
継続的インテグレーション(CI)を使用した公開
npmのTrusted Publisher機能を使用すると、OpenID Connectを利用したCIを素早くセットアップできます。 このアプローチにより、トークンの生成と管理が完全に不要になります。
この例では、GitHub Actions を使用したワークフローを設定します。
GitHub Actionsワークフローファイルの作成
GitHub Actionを設定する .github/workflows/publish.yml ファイルを作成します。
# .github/workflows/publish.yml
name: Publish
on:
release:
types: [released, prereleased]
permissions:
id-token: write # GitHub ActionsがnpmのTrusted Publishingと
# 連携するために必要です
contents: read
jobs:
publish:
name: Release build and publish
runs-on: ubuntu-latest
steps:
# トリガーとなったブランチをチェックアウト
- name: Check out code
uses: actions/checkout@v4
# Gradleタスクを実行するためのJDKをセットアップ
- name: Set up JDK 21
uses: actions/setup-java@v4
with:
distribution: 'zulu'
java-version: 21
# ライブラリモジュールのnpm公開Gradleタスクを実行
- name: Publish to npm
run: ./gradlew :shared:publishJsPackageToNpmjsRegistryこのファイルをプロジェクトをホストしているGitHubリポジトリにコミットしてプッシュすると、そのリポジトリでGitHubリリースが作成されるたびにワークフローが実行されます。
リポジトリにタグがプッシュされたときにトリガーするようにワークフローを設定することもできます。
GitHub ActionsをTrusted Publisherとして設定
ワークフローをプッシュしたら、GitHub Actionを使用してnpmパッケージにTrusted Publisherを追加できます。
- 公開済みパッケージのページを開きます。
- Settings タブを開き、Trusted Publisher セクションを見つけます。
- Select your publisher の下にある GitHub Actions ボタンをクリックします。
- フォームに入力します。
- GitHubの名前(またはOrganization)
- リポジトリ名
- ワークフローファイル名(このチュートリアルでは publish.yml を使用しました)。
- Setup connection ボタンをクリックします。

npmは入力された座標情報を検証しないため、詳細を正しく入力していることを確認してください。
作成された接続は、パッケージの設定にある Trusted Publishers セクションに一覧表示されます。 これにより、指定された座標のワークフローがnpmへの公開を承認されたことになります。
GitHubでリリースを作成する
ワークフローとTrusted Publisherの接続が設定できたら、GitHubリリースを作成して公開をトリガーする準備が整いました。
build.gradle.ktsの設定で、パッケージのバージョンを公開したいバージョンに設定します。バージョン番号がすでに使用されている場合、またはすでに公開されているバージョンより低い場合、npmは公開を許可しません。
GitHubリポジトリに移動します。
右側のサイドバーで Releases をクリックします。
Draft a new release ボタン(このリポジトリで過去にリリースを作成したことがない場合は Create a new release ボタン)をクリックします。
Gitタグを作成または選択します(システム間での番号の一貫性を保つため、可能な限りモジュールのバージョンと一致させてください)。
リリースのタイトルを設定します(タグと同じ名前にすると便利です)。
すべてを把握しやすくするために、タグのバージョンは
build.gradle.ktsファイルで指定したライブラリのバージョン番号と同じにすることをお勧めします。
Publish release ボタンをクリックします。
Actionがトリガーされたかどうかを確認するには、GitHubリポジトリのページ上部にある Actions タブをクリックします。 新しく公開されたリリースによって、公開ワークフローの実行がトリガーされたことが確認できるはずです。 ワークフローをクリックすると、公開タスクのログを表示できます。
ワークフローの実行が完了すると、npmレジストリのパッケージページにパッケージの新しいバージョンが表示されます。

