ページ内で書いていること

node.js の npm コマンド標準でインストールできるパッケージは「npmjs」にて管理されています。 今回、npm パッケージを公開したので、自分なりの手順を記録したものです。

公開までの手順

1. npm パッケージ のプロジェクトを作成
2. npmjs にアカウントを作成（無料）
3. npmjs に作ったパッケージを公開する

1. npm パッケージ のプロジェクトを作成

自分が公開するパッケージの package.json に、npm で公開する内容を記載します。

下のは例です。

{
  "name": "gatsby-remark-text-decoration",
  "version": "1.0.0",
  "description": "Decorate gatsby markdown text(.md) with short ext-tags.",
  "main": "index.js",
  "scripts": {
    "test": "jest"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/nodachisoft-com/gatsby-remark-text-decoration.git"
  },
  "keywords": [
    "gatsby",
    "gatsby-plugin",
    "gatsby-remark",
    "text decoration"
  ],
  "author": "Amaji(https://nodachisoft.com/)",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/nodachisoft-com/gatsby-remark-text-decoration/issues"
  },
  "homepage": "https://nodachisoft.com/",
  "devDependencies": {
    "jest": "^26.6.3"
  },
  "jest": {
     : テスト関係
  }
}

特に関係のある項目のみピックアップして、下のような内容で書いていきます。

例えば、npm search した時の結果は下のようになります。

package.json で登録した内容が検索時にも表示されてますね！

> npm search gatsby text decoration
NAME                      | DESCRIPTION          | AUTHOR          | DATE       | VERSION  | KEYWORDS
gatsby-remark-text-decora | Decorate gatsby…     | =amaji          | 2021-01-30 | 1.0.4    | gatsby gatsby-plugin gatsby-remark text decoration
tion                      |                      |                 |            |          |

npmパッケージの作成

エントリポイントの javascript ファイル（上の例では index.js） に以下のような形でモジュールを書いていきます。

module.exports = function() {
   : npmパッケージとして実現する機能
}

CommonJS 形式の module.exports で指定した function が他の javascript から参照されます。

公開前に

パッケージを npmjs 上に公開する前に、一応、セルフチェックしていきましょう。 公開するパッケージの内容が正しいことを確認しておきます。

変なファイルを世界に公開しないように、注意です！

テストコード確認

公開するプログラムのテストコードを書いているなら、テストがすべて成功して、ちゃんと動作するパッケージになっていることを確認します。

公開したくないファイルを制限する

npm で公開するすとき、公開するパッケージに含めないファイルを指定できます。 指定には以下の方法があります。

• gitignore
• npmignore
• package.json の files 項目でファイル指定

.gitignoreファイル

git でプロジェクトを管理する時に、git サーバに登録する対象外にするファイルで、 npm に登録するコマンドを入力する時にもチェックされます。

通常開発しているときは、「*.log」や「node_modules/」をコミットしないよう 記載してあります。

*.log
.cache
node_modules/

などを書いておきます。 GitHub 等でプロジェクトを作成するとき、「Add .gitignore」にチェックを入れればテンプレートで作成されるので便利です！

.npmignoreファイル

コチラのファイルがあれば、 .gitignore ファイルは無視され、.npmignore ファイルが 優先して確認されます。 オプションなので、ファイルがなくても大丈夫です。

こちらには、 npm の実行に関係ないテストモジュール等を書いておくとよいです。

*.log
.cache
__tests__
node_modules/

files指定

package.json にて、直接 npm パッケージで公開する方式です。 オプションなので、記載していなくても大丈夫です。

package.json 内にて files 項目を記載していきます。ホワイトリスト方式で、 ここに書いてあるファイルは npmレジストリに登録されます。

.gitignore や .npmignore ファイルで除外しても、ここに記載してるファイルは対象になります。

例えば index.js のみで動作するなら、下のように書いておきます。

"files": [
    "./index.js"
  ],

詳細な仕様はコチラ（公式 - docs.npmjs.com - package.json - files）をご参照ください。

2. npmjs にアカウントを作成（無料）

公式ページからアカウント作成できます。最低限、必要なのはメールアドレスくらい。

npmjs.com - 公式のサインアップページ にアクセスし、 アカウントを作成します。

• 1. username には好きなユーザ名を入れます。プロフィールで公表されます。例えば私のアカウントのプロフィールは「https://www.npmjs.com/~amaji」から見えます。アカウントを作ると、自動的に https://www.npmjs.com/~〇〇 (〇〇はユーザー名) のページが作成され一般公開されます。
• 2. E-mail はパッケージ公開する時にメタ情報として付与されます。一般公開される可能性があります。プロフィールからは見えませんし、勝手に package.json に付与されたりはしません。ですが、スパムメールとかが嫌な人は専用のアカウントを用意してもよいかも。
• 3. パスワードを入れます。
• 4. 利用規約に同意したらチェック。
• 5. 上記1～4 が終わったらボタンを押してアカウント作成完了！

3. npmjs に作ったパッケージを公開する

ではでは、自作パッケージを npm コマンドでインストールできるように一般公開していきましょう！

npmへログイン

npm に公開するためのアカウントでログインします。

開発環境でコンソールを立ち上げ、npm login コマンドでログインします。

> npm login
Username: npmjs で作成したあなたのユーザ名
Password: npmjs で作成したあなたのパスワード
Email: (this IS public) npmjs で入力したメールアドレス
Logged in as <username> on https://registry.npmjs.org/.

で先ほど作成した npm のパスワード、メールアドレスを入力します。 ログインが成功したら Logged in as <username> on https://registry.npmjs.org/. というメッセージが表示されます。

2021年12月現在、さらにワンタイム・パスワードが求められるようになりました。 登録したメールアドレスにワンタイム・パスワードが送信されてくるので、 必要に応じて確認＆入力しましょう！

公開する

ログインした後、 公開したいプロジェクトフォルダ直下で、npm publish コマンドで公開できます。

実行例

ここでは、例として「gatsby-remark-text-decoration」という名前の自作パッケージを登録しました。

実行ログの最後に以下のような表示がされていれば、無事にパッケージが npm レジストリに追加完了です。

やりました、お疲れ様です！！

+ gatsby-remark-text-decoration@1.0.0

ログインするnpmレジストリ npm login コマンドでオプションに何も指定しなければ、 デフォルト設定で「https://registry.npmjs.org/」へのログインとなります。 自前でレジストリ管理する場合はログイン先を任意に指定しましょう！ 詳細なコマンド仕様はコチラ（公式） npmjs.com - CLI - npm-adduserをご参照ください。

npmjsからログアウト

npm logout コマンドで作業が終わったらログアウトしておきましょう。

npm logout

特に実行結果にはなにも出ませんが、ちゃんとログアウトできています。

npmからインストールしてみる

一般公開されたかを確認するために、新しい node.js のプロジェクトを作成して、 先ほど公開したパッケージをインストールしてみましょう！

適当にフォルダ「testpackage」を作成してインストールしてみます。

> mkdir testpackage
> cd testpackage
> npm init
 : npm init の中身は適当。全部「Enter」でデフォルトでOK
> npm install gatsby-remark-text-decoration
npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN testpackage@1.0.0 No description
npm WARN testpackage@1.0.0 No repository field.

+ gatsby-remark-text-decoration@1.0.4
added 1 package from 1 contributor and audited 1 package in 1.689s
found 0 vulnerabilities

ちゃんとインストールされました！ お試し用のフォルダ「testpackage」配下に「node_modules」フォルダが作成されて、パッケージが追加されています。

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

作成した npm パッケージを更新する時には、 初回同様、npm login したのちに、 npm publish コマンドで更新できます。

ただし、その際には package.json の中の Version の数値を上げる必要があります。 バージョンの数値の上げ方はセマンティックバージョニングというルールに従います。

とりあえず npm パッケージの利用者からみて関数などの API が変更されない、 マイナーバージョンアップであれば 1.0.0 → 1.0.1 のように 「.」ドット区切りの一番右側の数字を一つ上げていきます。

このバージョンを変更せずに、npm publish コマンドを打つと、「バージョンかぶってますよー」というエラーが表示され、 更新は失敗します。

npm ERR! code E403
npm ERR! 403 403 Forbidden - PUT https://registry.npmjs.org/gatsby-remark-text-decoration - You cannot publish over the previously published versions: 1.0.4.
npm ERR! 403 In most cases, you or one of your dependencies are requesting
npm ERR! 403 a package version that is forbidden by your security policy.

npmパッケージを削除したい

npm unpublish コマンドで削除できます。 ただし、一度公開した「パッケージ名＋バージョン」は２度と npm レジストリでは登録できません。

確認した環境とバージョン

• OS: Windows 10 Home, version 2004
• node-js: v12.18.2, v16.13.1
• npm: v6.14.5, v8.1.2

おわりに

今回自作した npm パッケージを公開する手順をまとめておきました。

有用なプログラムを書いている方々が、一般公開する手助けになったら嬉しいです！

非常に参考になったサイトさまや、参考文献など

(英語)npmjs.com - CLI - npm-adduser

(英語)npmjs.com - CLI - npm-logout

(英語)npmjs.com - gatsby-remark-text-decoration

Github - gatsby-remark-text-decoration

権利など

• npmは npm, Inc. の登録商標です。

ページの更新履歴