npm パッケージを作って公開してみた

npm パッケージを Fork して公開してみたいなーと思い、まずはまっさらな状態から npm パッケージを公開するまでの方法を調べた。

ざっくりとした流れは以下のとおり。

1. npmjs にユーザ登録する
2. npm adduser でログインする
3. npm init でパッケージを作る
4. エントリポイント (index.js) の作成
5. CLI (bin/my-module) の作成
6. .npmignore の作成
7. npm publish で公開する

今回この手順で作ってみたサンプルパッケージは以下。

• @neos21/neos21 - npm

ついでにこのサンプルパッケージの実装は以下。

• GitHub - Neos21/npm-neos21: npm package example

では、この手順を詳しく説明する。

1. npmjs にユーザ登録する

まずは npm パッケージを公開している公式のリポジトリである、npmjs でユーザ登録を行う。

「Sign up for npm」から

• Name (任意の名前 : 表示用)
• Public Email (メアド : このアドレスに登録確認メールが飛んでくる)
• Username (スコープ・パッケージに使用されるユーザ名)
• Password (パスワード)

を登録する。

「Username」は npm パッケージの作者として表示される他、「@angular/cli」などのように「@ユーザ名/パッケージ名」という「スコープ・パッケージ」を作る時の「@ユーザ名」部分にあたる。

スコープ・パッケージは、元々プライベートモジュールを有料で扱えるもので、パブリックなパッケージなら無料で使えるようになった。これまでの npm パッケージ名は早い者勝ちだったが、ユーザ名を付与することで名前空間の衝突を避けられるようになった。

登録するとメールアドレスに確認のメールが飛んで来るので、URL にアクセスしてユーザ登録完了。

2. npm adduser でログインする

続いてターミナルで $ npm adduser を実行する。ユーザ名とパスワードを聞かれるので入力すると、~/.npmrc にトークンが追記される。これで npm publish ができるようになる。

トークン情報はホームディレクトリの ~/.npmrc である必要はなく、npm パッケージと同じディレクトリに置いた .npmrc に書いておいても大丈夫な様子。ただしうっかりこのトークンを含んだ .npmrc を GitHub などに公開しないよう注意。

3. npm init でパッケージを作る

いよいよパッケージ作成。といっても、普段 npm パッケージを使うプロジェクトで行っているのと同じように、最初は npm init で始める。

今回はまず GitHub でパッケージ用のリポジトリを作り、それを git clone してきてから npm init する。こうすることで package.json にデフォルトで色々記載してもらえるので楽になる。

$ git clone https://github.com/【ユーザ名】/【リポジトリ名】
$ cd 【リポジトリ名】/
$ npm init

パッケージ名は @【ユーザ名】/【パッケージ名】 という書き方にするとスコープ・パッケージが作れる。npm init --scope=【ユーザ名】 と始めると自動補完してくれる。勿論後から package.json を手修正して @【ユーザ名】/【パッケージ名】 としても問題ない。

ちなみに、試してみたところ @neos21 というユーザ名と同じパッケージ名では npm publish することができなかった。スコープ・パッケージのユーザ名部分に付く @ は特殊な解釈を行っているようである。

エントリポイント (index.js) の作成

まずは package.json の main に記載される index.js を作る。これが、npm パッケージを require() した時に使えるモノとなる。

今回は、ただユーザ名と URL をコンソール出力するだけのファイルを作ってみた。

// index.js
function Neos21() {
  console.log('@neos21');
  console.log('http://neo.s21.xrea.com/');
}

module.exports = Neos21;

require() で使うために module.exports を忘れないこと。

CLI (bin/my-module) の作成

次に、グローバルインストールした時や npm run などで呼ぶ時に実行される、コマンドラインモジュールを作る。

bin/ ディレクトリを作り、コマンド名となるファイル名 neos21 を作ってみる。ユーザ名と URL を出力するだけのコマンドだ。

#!/usr/bin/env node

console.log('@neos21');
console.log('http://neo.s21.xrea.com/');

そしてこれをコマンドラインで呼び出せるようにするため、package.json に bin プロパティを追加する。

"main": "index.js",
"bin": "bin/neos21",

.npmignore の作成

.npmignore は npm publish する際に公開しないようにするファイルを設定するもの。.gitignore があって .npmignore がない場合は、.gitignore がそのままリネームされて .npmignore となって Publish されるようだ。

書き方は .gitignore と同じで、無視したいファイルやディレクトリを書けば良い。

4. npm publish で公開する

これでとりあえず完成。おもむろに $ npm publish --access=public を叩いてみると、あっという間に公開される。スコープパッケージの場合は --access=public オプションを付けないとプライベート扱いになるためオプション必須。

公開されたパッケージは以下のような URL で確認できる他、$ npm search 【パッケージ名】 で検索して表示されるようになる。

• @neos21/neos21 - npm

実際にパッケージを使ってみる

それでは実際にパッケージを使ってみる。

まずは適当なプロジェクトでローカルインストールし、index.js に作った関数を実行してみる。

# パッケージを利用する適当なプロジェクトを作る
$ mkdir test-project && cd $_
$ npm init -y

# パッケージをローカルインストールする
$ npm install @neos21/neos21 --save

# パッケージを呼び出して利用する JS ファイルを作ってみる
$ touch test.js

test.js ファイルには以下のように実装する。

// パッケージを読み込む
var neos21 = require('@neos21/neos21');

// 読み込んだパッケージの関数を実行する
neos21();

これで出来上がり。Node.js で test.js を実行してみると、正しくパッケージが読み込まれ、ユーザ名と URL が表示されるだろう。

# パッケージを利用しているスクリプトを実行する
$ node test.js
@neos21
http://neo.s21.xrea.com/

次に、グローバルインストールをしてコマンドラインモジュール (bin/neos21) を使ってみる。

# パッケージをグローバルインストールする
$ npm install -g @neos21/neos21

# パッケージを実行してみる
$ neos21
@neos21
http://neo.s21.xrea.com/

ご覧のとおり。

これで npm パッケージの作成から公開まではとりあえず試せた。

• 参考 : npmで名前空間を持ったモジュールを公開する方法(scoped modules) | Web Scratch
• 参考 : 3分でできるnpmモジュール - Qiita
• 参考 : 初めてのnpm パッケージ公開 - Qiita