npmパッケージ公開の備忘録 2021年版
技術・テクノロジー最近 rehype-title-figure という npm パッケージを公開したのですが、普段あまり npm パッケージを公開することがなく、詰まった点がいくつかあったので自分がやったことを備忘録としてまとめておきます。
npm パッケージ公開までの流れ
1. プロジェクトの作成
まずは適当なディレクトリを作成してnpm initコマンドを実行します。
こうするとpackage.jsonができるので、最低限必要そうな項目を追加しておきます。個人的には
- description
- repository
- homepage
- bugs
- keywords
あたりは追加しておくといいんじゃないかなぁと思いますが、中にはリポジトリの情報がないと埋められないものもあるので、先に GitHub 等でリポジトリを作っておくのが良いかもしれません。
2. コードを書く
今回は TypeScript を使いたかったので、typescriptをインストール後、yarn tsc --initでtsconfig.jsonを生成してコードを書き始めました。
ソースコードはsrcディレクトリ以下に格納し、outDirとしてlibディレクトリを指定、この時点で npm パッケージとして管理したいファイルをpackage.jsonの"main"および"files"プロパティに書いておきます。
また、今回はtestsディレクトリ以下にテストコードも追加しています。テストのカバレッジは Codecov で管理するようにします。
3. 開発を便利にするツールを追加
この時点でやることはほぼ終わっているのですが、その他にやっておくと便利かな？と思うことを説明しておきます。
まず、コードフォーマッターとしてprettierを入れ、フォーマットのコマンドを npm scripts に残しておきます。
次に、Conventional Commits を用いてコミットメッセージやバージョンの管理を行いたいので、standard-versionを導入し npm scripts も更新します。
さらに、これはコミット時にチェックしたいので、huskyも入れておきます。
最後に、自動でフォーマットのチェックやテストを走らせるために GitHub Actions も導入しておきます。
4. README や LICENSE の整備
パッケージを公開する前に、最低限の説明をREADME.mdに書いておくと良さそうです。自分はパッケージのインストール方法と簡単な使い方を書いておきました。
また、パッケージの先頭にはバッジを表示しておくと華やかになります。
追加で、ライセンスの情報もLICENSEファイルに残しておきます。
5. パッケージを公開する
まだ一度も npm のパッケージを公開したことがない方は、npm にてアカウントを作成し、npm adduserコマンドでユーザー情報の追加をしておく必要があります。
この状態でyarn standard-version --first-releaseコマンドを実行すると、CHANGELOG.mdの作成や git のタグづけ、バージョンの更新などを行ってくれます。また、もしコマンドの実行の動作だけを確認したい場合は--dry-runオプションを付与して確認すると良いと思います。
無事yarn standard-version --first-releaseが実行できたら、あとはnpm publishでパッケージを公開するだけです。このコマンドに関しても、--dry-runオプションを付与することで実際に公開せず、動作のみ確認できます。
一度 npm パッケージを公開した後でパッケージの更新を行いたい場合は、リリースしたいタイミングでyarn standard-versionを叩き、npm publishを行えば良いです。
間違えてパッケージを公開した場合
npm unpublishコマンドで、公開したパッケージの公開を取りやめることができます。これは公開してから 72 時間以内であれば可能です。72 時間以上経過したときの詳細は以下を確認してみてください。
また、地味な注意ポイントとして、初回のパッケージ公開後、そのパッケージ公開をやめたい場合、npm unpublish [パッケージ名] --forceではなくnpm unpublish [パッケージ名]@[バージョン]にて、バージョン指定してパッケージの非公開化を行わないと、再度同じバージョンを公開しようとした際にエラーになるので注意が必要です。
一度非公開とした場合、再公開は 24 時間後以降でないと行えません。自分は初回に公開したパッケージをnpm unpublish [パッケージ名] --forceで非公開にし、24 時間後に再度公開しようとした際に「そのバージョンはすでに公開済みだよ」というエラーになってしまい、再度npm unpublish [パッケージ名]@[バージョン]で指定バージョンの公開をとりやめ、さらにその 24 時間後に改めて公開、というかなり無駄が多いことをやってしまいました･･･😅
まとめ
かなり雑な説明ではありますが、細かい設定などは 公開しているリポジトリ を見ていただければわかるかな、と思います。
また、今回はとりあえず動くものが公開できればいいや、と思って開発したので、そこまで凝ったことはしていないのですが、実際はビルドした生成物をもっと整備したり、開発時のツールも増やしたりして良さそうです。
その辺の詳しい設定などは、有名な OSS のリポジトリを参考にすると良いかな〜と思うので、次にパッケージを公開する機会があればパッケージの規模に応じてよりよい構成にしていきたいですね。
参考にさせていただいたリポジトリ
さいごに、今回開発するにあたって参考にさせていただいたリポジトリをまとめておきます。
