Zenn
📝

Node パッケージ を npmjs に公開するうえで知っておくべきこと

2024/06/25に公開
GitHub
JavaScript
Node.js
npm
tech

これはなに

自作した Node.js パッケージを npmjs に公開するうえで知っておくべきことをまとめたものです。npmjs は Node.js パッケージレジストリーとして広く利用されていますが、パッケージ公開にはいくつかの注意点があります。本稿では、npmjs にパッケージを公開する際に必要な知識や手順をご紹介します。

Semantic Versioning

https://semver.org/lang/ja/

npmjs にパッケージを公開する際には、必ずバージョン番号を付与する必要があります。また、一度公開されたバージョンのパッケージはいかなる理由があろうと変更できず、修正を加えるには新しいバージョンとして公開せねばなりません。つまり、一度使用されたバージョン番号は再利用できず、パッケージをアップデートして公開するたびにバージョン番号を更新することになります。このバージョン番号は闇雲にインクリメントするのではなく、一定のルールに基づいて更新するのが望ましいとされています。

Semantic Versioning は、現在最も広く利用されているバージョン番号のルールです。Semantic Versioning に従うことで、他の開発者がパッケージのアップデート内容を容易に把握できるようになります。

バージョン番号の構成

一般的にバージョン番号は 1.10.5 のように表記されます。この例では、1 がメジャーバージョン、10 がマイナーバージョン、5 がパッチバージョンを表しています。

1.10.5
| |  |
| |  └── パッチバージョン
| └───── マイナーバージョン
└─────── メジャーバージョン
説明
メジャーバージョン 後方互換性のない（破壊的な）変更が行われた場合にインクリメントされます。
マイナーバージョン 後方互換性を保ったまま機能追加が行われた場合にインクリメントされます。
パッチバージョン 後方互換性を保ったままバグ修正が行われた場合にインクリメントされます。

重要なのは後方互換性が保たれているかどうかであり、バージョン番号の変更はこの観点から行われます。メジャーバージョンの変更は後方互換性が保たれていないことを意味するため、パッケージ利用者はアップデートの際に予期せぬ問題が発生する可能性をあらかじめ認識したうえで臨めるようになります。また、パッチバージョンの変更はバグ修正が行われたことを意味するため、利用者は安心してアップデートを行えることが事前に伝わります。

Alpha / Beta / RC / Stable

先述したバージョン番号とは別に、開発の途中段階であることを示す識別子を付与することがあります。これにより、パッケージ利用者は安定版と開発版を識別して導入を検討できます。

1.0.0-alpha.1
1.0.0-beta.1
1.0.0-rc.1
1.0.0 # Stable

一般的な識別子は以下のとおりです。

説明
Alpha (alpha) 新機能の追加や変更が頻繁に行われる段階であり、まだ不安定な状態であることを示します。
Beta (beta) 予定されている機能が完備され利用可能となったこと、リファクタリングや不具合修正に取り組んでいる段階であることを示します。
Release Candidate (rc) 予定されている機能は完備されて動作が安定しており、公開 QA を実施するなどして最後のバグ修正を行っている段階であることを示します。
Stable 公開 QA および報告された修正タスクが完了し、間もなく正式リリースが告知される段階であることを示します。

Release Notes

各バージョンに加えられた変更内容が明記されたドキュメントです。パッケージの開発当事者にとっては自明な内容ですが、一般の利用者にとっては知らない情報です。パッケージの利用者がアップデートを行う際に Release Notes を参照して変更内容を把握してもらうことは非常に重要です。Release Notes は CHANGELOG.md といったドキュメントに書き起こしてリポジトリーに含めるのが慣例ですが、GitHub であればリポジトリーに付随するリリースノートページも広く利用されています。

説明
パッチリリース 軽微なバグ修正であれば、その旨を簡潔に記述するだけで済まされることが多い。
マイナーリリース 新機能の追加や既存機能の変更が行われた場合、そのユースケースといった使い方に関する情報を記述する。
メジャーリリース 「どの機能を削除・追加したか」「旧バージョンから移行するために必要な手順」を記述する。

Node パッケージの設定

package.json には様々な設定項目がありますが、npmjs にパッケージを公開する際には特に以下の事項に注意する必要があります。

npm-access

https://docs.npmjs.com/cli/v7/commands/npm-access

パッケージの公開範囲を指定します。デフォルト値は restricted となっており、特定の権限を持つユーザーのみがパッケージをインストールできるようになっています。一般公開したい場合は public に設定します。

package.json
{
  "name": "my-package",
  "version": "1.0.0",
  "publishConfig": {
    "access": "public"
  }
}

また、名前空間を持ったパッケージを公開する場合や、無料の npmjs Organization アカウントに紐付けて公開する場合も public にする必要があります。

package.json
{
  "name": "@my-org/my-package",
  "version": "1.0.0",
  "publishConfig": {
    "access": "public"
  }
}

公開するファイル・ディレクトリーの指定

開発時には必要だが、公開・配布する際には不要なファイルやディレクトリーがあります。例えば src や .github といったディレクトリー、.node-version  のようなのような開発環境固有の設定ファイル群が挙げられます。このようなファイル達が配布物に混入するのを避けるため、公開するファイル・ディレクトリーを指定するのが望ましいです。指定する方法は主に以下の 2 つです。

1.files フィールド（ホワイトリスト）

package.json の  files  フィールドは、配布する Node モジュールに含めるべきファイルやディレクトリーを記述するフィールドであり、まさにホワイトリストとして機能します。具体的には npm モジュールに含めるファイル名やディレクトリー名を記述します。

package.json
{
  "name": "my-package",
  "version": "1.0.0",
  "files": [
    "index.js",
    "dist",
    "lib"
  ]
}

上記のように書くと  index.js ファイル、および  dist, lib  ディレクトリー配下が配布するパッケージに含まれ、他のファイルは除外されます。ただし、以下のファイルは利用者にとって必要不可欠なため、上記の設定に関わらず必ず含まれます。

  • package.json
  • README
  • LICENSE

2..npmignore に列挙する（ブラックリスト）

.npmignore ファイルに列挙したファイルおよびディレクトリーは、 配布物から除外されます。

.npmignore
.github/
.vscode/
.node-version
.npmrc

.npmignore  は、言うなればブラックリストです。ブラックリストは、未知のファイルに対して無防備になりがちであることも意味します。

files フィールドと .npmignore を併用する

package.json の  files  フィールドは  .npmignore  ファイルとの併用が可能です。例えば  test  ディレクトリー内に配布物から除外したいファイルが複数ある場合は、そのファイルたちを除外するパターンを  .npmignore  に書くことで、 files フィールドが冗長になるのを防げます。

まずは  files  フィールドにホワイトリストを列挙し、その中から個別に除外したいパターンがあれば  .npmignore  に書く、という組み合わせが適切でしょう。

NPM Access Token

https://docs.npmjs.com/about-access-tokens

Node パッケージを npmjs に公開するには、npmjs のアカウントおよびそれが発行するアクセストークンが必要です。アクセストークンは npmjs の API を利用する際に必要となる認証情報であり、パッケージの公開や削除、ユーザー情報の取得などの操作を CLI や GitHub Actions のようなシステムから行う際に使用します。

NPM Access Token の発行手順

npmjs.com のアカウントメニューから Access Tokens ページに進み、Generate New Token > Granular Access Token メニューを選択します。

generate new token

以下の項目を埋めて Generate token ボタンをクリックすれば、アクセストークンが発行されます。

項目 説明 特記事項
Token name アカウントにつきユニークであること。
Expiration トークンの有効期限。 Granular Access Token だと無期限は不可。
Packages and scopes
Permissions 		トークンの権限。 Read and write を選択する。
Packages and scopes
scopes 		トークンが有効となる名前空間もしくは Node パッケージの一覧。 All Packages を選択すると、このアカウントがメンテナーとなる全てのパッケージに対し有効となる。
Organizations
Permissions 		トークンが有効となる Organization の一覧。 @<org-name>/<pkg-name> という名前で公開したい場合は Read and write を選択する。
そうでなければ設定不要。

トークンが有効となる名前空間および Node パッケージとして選択可能なのは、そのアカウントがメンテナーとなっているものに限られます。つまり他のアカウントが公開したパッケージに対してトークンを有効化するには、あらかじめそのパッケージのメンテナーとなっている必要があります。

また、Node パッケージ名を @<org-name>/<pkg-name> とするということは、 npmjs の Organization に紐付けることを意味します。そのためには Organizations > Permissions を設定したアクセストークンを発行する必要があります。

参考文献

Discussion