かもメモ

自分の落ちた落とし穴に何度も落ちる人のメモ帳

初めての npm パッケージ公開したメモ

npm JavaScript Tips

よわよわな npm のパッケージ公開したみたので、パッケージ公開までのハマりどころとかをメモ

公開した npm パッケージ

1. npm アカウントの作成

npm のサイト からアカウントを作成する。
Sign Up のフォームにも書かれているが、npm のアカウントのメールアドレスは公開されるので、公開されても問題ないメールアドレスでアカウントを作るのが良いと思う。

2. ターミナルで npm にログインする

npm に接続するためにターミナルから先ほど作成した npm アカウントでログインする。 npm login コマンドを実行して訊かれるものに答えればOK。二段階認証してると二段階認証も訊かれる。

$ npm login
Username: # アカウント名
Password: # パスワード
Email: (this IS public) # 登録したメールアドレス
Enter one-time password from your authenticator app: # 二段階認証

3. 公開するパッケージの作成

npmに公開する場合 git 管理下にある必要があるので、GitHubに公開したいパッケージのリポジトリを作成してローカルにcloneする。(別にGitHubでなくてもいい)
clone したディレクトリに入ってnpm init か yarn init でプロジェクトを作成する。
package.json にある情報が npm に公開される情報になる。 (npm と yarnとで作成される package.json が微妙に異なる )

package.json

{
  "name": "PACKAGE_NAME", // npm に公開されるパッケージ名
  "version": "1.0.0", // パッケージのバージョン
  "description": "", // パッケージの説明。npm で検索した時に表示される
  "main": "index.js", // entry point になるファイル
  "keywords": [], // npm に公開した時にキーワードタグになる
  "license": "MIT",
  ...
}

GitHubのリポジトリ下で npm init すると自動的に repository を GitHub に、 homepage を GitHub の README、bugs を GitHub の issues に設定してくれる。

description はパッケージのページには表示されないけど、検索した時に表示される。似たパッケージがあるとこ description でアクセスするかどうかが決まりそう。
package.json description

4. パッケージを npm に公開

公開するプログラムを作成したらパッケージを公開します。
babel とかでビルドしたものが entry point (実際に使用されるコード)になる場合は、ビルドしたものを git 管理下に置いておくか、公開時にビルドされる用設定しておく必要がある。

ビルドスクリプトの作成

package.json に npm スクリプトを作成する。
公開時のコマンドは色々と変遷があるようで、では

  • prepublish ではなく prepublisOnly を使うのが良さそう
  • 将来的に prepublisOnly は非推奨になり prepublish が推奨されるようになるらしい

公開時に babel を実行する場合はこんな感じ
package.json

{
  "scripts": {
    ...
    "build": "./node_modules/.bin/babel --source-maps",
    "prepublishOnly": "npm run build"
  }
}

パッケージの公開

npm publish ./ コマンドを実行するとファイルが npm にアップされてパッケージが公開される。

$ npm publish ./
...
npm notice
...
+ YOUR_PACKAGE@1.0.0

コマンドを実行して ERR がなく最後にパッケージ名@バージョンが表示されればOK
npm で検索するか自分のアイコンのメニューから packages を選べば公開されているパッケージが表示されているはず 🎉

パッケージのアップデート

npm version コマンドでバージョンを上げることができる。
アップデートの規模によって patch, minor, major を使い分ける。コマンドを実行すると package.json の version が変更され、バージョンの tag が作成され git commit される。( git push はされない )

patch

$ npm version patch
v1.0.1  # v1.0.0 から v1.0.1 にバージョンアップ

minor

$ npm version minor
v1.1.0  # v1.0.1 から v1.1.0 にバージョンアップ

patch バージョンは 0 に戻る

major

$ npm version major
v2.0.0  # v1.1.0 から v2.0.0 にバージョンアップ

patch, minor バージョンは 0 に戻る

パッケージ公開のハマりどころ

1. npm のパッケージ名には大文字が使えない

Uppercase characters are disallowed in new package names.
ref. npm publish failed put 400; is invalid for new packages · Issue #15787 · npm/npm · GitHub

e.g.

// package.json
{
  "name": "isObject",
}

大文字を含むパッケージ名にしていると、パッケージ公開時の publish で ERR! code E400 Bad Request というエラーになる。
エラーからは原因が分かりにくいのでハマりどころ…

2. @付きのパッケージ名( scoped package )にしたい時

@babel/core みたいなスコープのあるパッケージにしたい時、@XXXX なスコープ名は npm のアカウント名か組織名でないと公開できないみたい。
アカウント名と異なる @XXXX/ を指定したパッケージ名だと publish しようとしてもエラーになる。
僕の場合 npm のアカウント名を kikiki_kiki なんて長いのにしてしまったから、Scoped package にしたいと思うと @kikiki_kiki/xxxxx みたいな長い名前のパッケージ名にしかできない。(スコープモジュールにした自作パッケージの import がスゴイ面倒…)

When you sign up for an npm user account or create an Org, you are granted a scope that matches your user or Org name. You can use this scope as a namespace for related packages.
cf. About scopes | npm Documentation

3. public パッケージの場合は公開時に明示的に public であることを明示する必要がある

npm パッケージの公開

$ npm publish ./
npm notice
...
npm ERR! code E402
npm ERR! 402 Payment Required - PUT https://registry.npmjs.org/YOUR_PACKAGE - You must sign up for private packages

ERR! code E402 Payment Required というエラーになる。
private パッケージは有料プランなので、private なものを間違って public で公開してしまわないための処置なのかもしれない。
明示的に --access=public オプションを付けることで public パッケージとして公開される

$ npm publish --access=public ./
...
npm notice
...
+ YOUR_PACKAGE@1.0.0

Scoped package の場合はデフォルトがプライベートパッケージだと判断されるので公開パッケージにする場合は、初回の publish 時には明示的に --access=public を付ける必要がある。

Scoped packages are private by default; you must pass a command-line flag when publishing to make them public.
cf. About scopes | npm Documentation

4. 公開したパッケージは同じバージョンで上書きできない

npm は GitHub みたいに face push できないようなので、一度公開したバージョンをそのまま修正することはできないみたい。
修正する際は npm version patch などでパッケージのバージョンをアップデートして再 publish する必要がある

[参考]

NEW GAME! (9) (まんがタイムKRコミックス)

NEW GAME! (9) (まんがタイムKRコミックス)