npmのパッケージ公開入門

Node.jsを使うメリットは膨大なモジュールを備えるnpmの存在が大きいところです。既存の物を利用するだけでも良いのですが、npmには誰でも簡単にモジュールを公開することができる仕組みが備わっています。

Node.js / npm のインストール

macOSの場合、nodebrewからNode.jsをインストールしておくのがおすすめです。 詳細は以下の記事を。 blog.katsubemakito.net

Node.jsを入れるとnpmが自動で入ります。

ユーザー情報の登録

ユーザー情報をセット

自分の名前とメールアドレス等をローカルに記録します。npm setを実行すると~/.npmrcに内容が保存されるので念のため確認しておきます。

$ npm set init.author.name  "Makito Katsube"
$ npm set init.author.email "katsubemakito@gmail.com"
$ npm set init.author.url   "http://github.com/katsube"

$ cat ~/.npmrc
init.author.name=Makito Katsube
init.author.email=katsubemakito@gmail.com
init.author.url=http://github.com/katsube

npmにユーザー作成

今度はnpm上にユーザーを作成します。

$ npm adduser              
Username: katsube
Password: 
Email: (this IS public) katsubemakito@gmail.com
Logged in as katsube on https://registry.npmjs.org/.

しばらくするとnpmからメールアドレスの確認メールが飛んでくるので、URLをクリックしておきます。

チョロい←

npm ♥ you!

既存ユーザーでログインしたい場合

前任者から引き継いだ場合など、もしすでにnpmにユーザを保有している場合はnpm loginでログインします。

$ npm login 
Username: katsube
Password: 
Email: (this IS public) katsubemakito@gmail.com
Logged in as katsube on https://registry.npmjs.org/.

なお、現状ログインしているかどうかわからない場合は npm whoami と叩くとログイン中のユーザー名を表示してくれます。別のユーザーにログインし直したい場合はnpm logoutでログアウトした後にnpm loginすればOK。

パスワードがわからない場合はコチラから再設定を。メールアドレスが不明な場合はメールボックスにnpmから登録完了メールが来ているハズなので探し出してToを確認してください。

パッケージの準備

GitHubにリポジトリ作成

npmはGitHubと相性が良いので、適当な公開リポジトリを作っておきます。今回はちょうど作成しようとしていたツールがあったのでそれ用のリポジトリ名にしました。

先ほど作成したリポジトリを適当な場所にgit cloneしておきます。

$ git clone https://github.com/katsube/excel2sql.git
Cloning into 'excel2sql'...
warning: You appear to have cloned an empty repository.

package.jsonを作成する

パッケージの設定や情報を記録したpackage.jsonなるファイルを作成するのですが、npm initコマンドを実行すると対話方式で質問に応えていくと自動で作成してくれます。

$ cd excel2sql
$ npm init

項目	説明
package name	ディレクトリ名がデフォで入ります。お好きな英数字の文字列を
version	完成品を最初から上げない場合は 0.0.1 や 0.1.0などを入れます。
description	説明文。省略可能。
entry point	一番最初に実行されるファイルを指定します。
test command	省略可能
git repository	Gitのリポジトリが自動で入ります。別途指定したい場合は入力を
keywords	検索用のキーワード。省略可。複数ある場合はカンマで区切ります
license	ライセンスを指定します。こちらのページのIdentifier列の文字列を入力します

作成されたpackage.jsonは以下の通り。直接このファイルを編集することもできます。

{
  "name": "excel2sql",
  "version": "0.0.1",
  "description": "Create SQL from EXCEL file. CLI tool.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/katsube/excel2sql.git"
  },
  "keywords": [
    "SQL",
    "EXCEL",
    "CLI"
  ],
  "author": "Makito Katsube <katsubemakito@gmail.com> (http://github.com/katsube)",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/katsube/excel2sql/issues"
  },
  "homepage": "https://github.com/katsube/excel2sql#readme"
}

依存パッケージの設定

開発時に必要なパッケージを入れます。

$ npm install --save-dev (パッケージ名)

本番実行時に必要なパッケージは次のように入れます。

$ npm install --save (パッケージ名)

上記のコマンドを実行することで、実際にインストールされるとともに、packag.jsonにも次のような記述が追加されます。devDependenciesが開発用、dependenciesが本番実行用のパッケージ一覧です。

  "devDependencies": {
    "foo": "^1.0.0"
  },
  "dependencies": {
    "bar": "^1.0.0"
  },

プログラムの準備

npm init時に「entry point」で指定したファイルindex.jsなどを編集し実際のプログラムを記述します。とりあえず動かすためにindex.jsには次のように記述しました。

//I'm index.js
exports.echo = function(str){
  console.log(str);
}

その他に必要なファイルを準備

LICENSE.txt

LICENSE.txtという名前のファイルを作成し、ライセンスの条文を記述します。MITの場合は以下のページをコピペし となっている箇所を変更しておきます。 opensource.org

README.md

Markdown形式で説明文を記述します。内容は英文で書くのが好ましいですが、難しいようならGoogle翻訳に頼るか単語を羅列した物でも問題ないでしょう（大量にDLされたら考えれば良いです）。

内容としては以下のような物を簡潔に書いてあれば良いでしょう。

• 短文の説明 (description)
• install
• example
• api (method)
• License

GitHubへpushする

完成したらGitHubにpushするのを忘れずに。

$ git commit -am 'implements index.js'
$ git push 

タグも付けておきます

$ git tag v0.0.1
$ git push --tags

npmに公開する

npm publish

ここまで準備が終わっていれば、コマンド一発で公開できます。

$ npm publish
+ excel2sql@0.0.1

npmのサイトで実際に確認してみましょう。ほぼ一瞬で公開されます。恐ろしいですねｗ

npm installできるか確認

実際にnpm installできるか確認してみましょう。最初は中々感動しますｗ

### 適当なディレクトリを作成する
$ mkdir foo; cd foo

### npm installする
$ npm install excel2sql    
/Users/katsube/Desktop/foo
└── excel2sql@0.0.1 

実際に動かして遊んでみます。

$ cat foo.js
const excel = require("excel2sql");
excel.echo("Hello");

$ node foo.js
Hello

npmで公開したモジュールのバージョンを上げる

パッチを当てる

ちょっとした変更や修正の場合、コード等の修正が完了したら以下のようにまずバージョンをアップするところからはじめます。

$ npm version patch
v0.0.2

これでpackage.json内のバージョンが+0.0.1されます。また自動的に git tag も発行してくれるので、問題なければgit push --tagsしておきましょう。

$ git tag
v0.0.1
v0.0.2

$ git push --tags

最後にpublishすれば完了です。

$ npm publish

メジャー / マイナー バージョンアップ

v0.0.1 から v1.0.0など大規模なバージョンアップの場合は以下の通り。

$ npm version major
v1.0.0

v1.0.0 から v1.1.0 など中規模なバージョンアップの場合は以下の通り。

$ npm version minor
v1.1.0

最後は同様にpublishで完了です。

$ npm publish

CLIから利用可能なコマンドを登録する

npm installでパッケージを利用していると、コマンドラインで利用できるコマンドがインストールされることがあります。こいつにも挑戦してみましょう。

package.jsonに追記

プロパティを２つほど追加します。

    "preferGlobal": true,
    "bin":{
        "excel2sql": "cli.js"
    }

preferGlobalはグローバルへのインストールを推奨します(npm install -g)。 binで実際のコマンドの指定をするわけですが、これは {"コマンド名": "実行されるファイル"}という関係になっています。

コードの用意

とりあえず動かしてみたいので、以下のような最低限のコードを用意しました。

#!/usr/bin/env node
'use strict';
console.log("Hello");

ローカルで確認

npm linkと打つと、package.jsonに記述された内容に従ってコマンドを使えるようにしてくれます。

$ npm link

実際に実行してみると、あまりに簡単に作れてしまうので変な声を出してしまいましたｗ

$ excel2sql
Hello

コマンドライン引数を取得

コマンドラインから引数を取得したい場合は process.argv を参照します。

#!/usr/bin/env node
'use strict';
console.log(process.argv);

実際に実行してみると次のような感じで得ることができます。

$ excel2sql Hello
[ '/Users/katsube/.nodebrew/node/v8.9.4/bin/node',
  '/Users/katsube/.nodebrew/current/bin/excel2sql',
  'Hello' ]

process.argv[0]

Node.jsのパス

process.argv[1]

実行されたファイル

process.argv[2]〜

コマンドライン引数

環境変数を取得する

環境変数は process.env を参照します。

#!/usr/bin/env node
'use strict';
console.log(process.env);

もろもろ省略してますが、まるっと取得することができます。

$ excel2sql
{ TMPDIR: '/var/folders/xy/hdsg1p9955g_tgmgys668cmw0000gn/T/',
  LANG: 'ja_JP.UTF-8',
  TERM_PROGRAM: 'Apple_Terminal',
  TERM: 'xterm-256color',
  SHELL: '/usr/local/bin/zsh',
  HOME: '/Users/katsube',
  LOGNAME: 'katsube',
  USER: 'katsube',
  PATH: '/Users/katsube/.nodebrew/current/bin',

npmに公開する

ここまでで問題ない場合はnpmへ登録します。手順はこれまでと同じです。最終的にpublichをすれば公開されます。

$ npm publish

npmで公開したパッケージを削除する

公開してしまったパッケージを削除するにはnpm unpublishコマンドを実行します。

$ npm unpublish excel2sql --force
npm WARN using --force I sure hope you know what you are doing.
- excel2sql

ただしこれには制約があります。

• 24時間以内に公開されたバージョンのみ取りやめる(unpublishする)ことが可能
  • 24時間以上経過してしまった場合は support@npmjs.com まで問い合わせる
• 一度非公開にしたパッケージ名＋バージョンは再度公開することはできない
  • バージョンを変更すれば可能

詳しくはドキュメントを参照してください。 docs.npmjs.com

npmにパッケージを公開する手順としては、これくらい覚えておけばひとまず使えると思います。 慣れれば非常に簡単に追加できるのですが、面倒な点としてはドキュメントの用意ですかねｗ まぁ最初に勢いで作ってしまうしかないかもしれませんｗ

お疲れ様でした！

その他

依存パッケージをアップデートする

プロジェクトを作成したあとに時間が経過すると、npm installしたパッケージがどんどん更新されていきます。いつまでも古いバージョンをpackage.jsonで指定したままだとセキュリティ上好ましくありません。

依存パッケージの更新方法については以下の記事を参照ください。 blog.katsubemakito.net

参考ページ

• https://docs.npmjs.com/getting-started/publishing-npm-packages
• https://docs.npmjs.com/files/package.json
• https://docs.npmjs.com/cli/unpublish
• https://garafu.blogspot.jp/2016/11/packagejson-specification-ja.html
• https://qiita.com/TsutomuNakamura/items/f943e0490d509f128ae2

ハンズオンNode.js

Node.jsデザインパターン 第2版