More than 1 year has passed since last update.

「3分でできるnpmモジュール」に、公開のための手順がまとめられていて分かりやすかったので(感謝)、実際に3時間でモジュールを作ってみました。そのときにやったことのメモ。

(ちなみに、作ったのはPhantomJSをgulpから使いやすくするプラグインgulp-phantomです。よかったら使ってください〜)

なにするの?

  • モジュールのお膳立て
  • 実装
  • GitHubにソースコードを置く
  • npmに公開する

1時間目

まずはお膳立てから。最低限、必要なファイルはこのあたりです。1時間目に、太字のファイルからやっつけます。

  • package.json
  • .npmignore
  • .gitignore
  • .travis.yml
  • index.js
  • test/
  • LICENSE
  • README.md

package.json

こんな感じのやつですね。公開しないプロジェクトだと、dependencies以外、省略しているケースもあると思いますが、npmに上げる場合は、一通り記載しておきます。

package.json
{
  "name": "gulp-phantom",
  "description": "phantomjs plugin for gulp",
  "version": "0.0.1",
  "homepage": "https://github.com/cognitom/gulp-phantom",
  "main": "./index.js",
  ...
}

モジュールのルートフォルダに移動して、

$ npm init

とやると色々質問されるので、それに答えていくと package.json が作られます。適当に答えておいて、後で直せばOK。

仕様はここにまとめられていますが、設定ファイルの例を見ながら説明してくれるインタラクティブ ガイドが分かりやすいです。

以下、重要なところだけメモ。他は類推でいけると思います。

  • name モジュール名 (アルファベットとハイフンが使えます)
  • version とりあえず 0.0.1 (npmに上げるときには都度変更)
  • main モジュールが最初に読みにいくファイル (index.jsとしました)
  • dependencies 依存モジュール
  • devDependencies 開発時のみ使うモジュール
  • scripts テスト用のスクリプトを指定 (後述)
  • engines nodeのバージョン指定

注・ハマりかけたところ

他のモジュールを参考にしようと思って、node_modulesにインストールされたものを見ると、 package.json にやたらいろいろ書いています。が、下記のものは手入力しなくてOKです。npmコマンドが勝手に補完してくれるので、気にせずスルーしましょう。

  • readme
  • readmeFilename
  • bugs
  • _id
  • _from

.npmignore

必ずしも必要はありませんが、tmp/ディレクトリを外したいとかいった場合に指定します。

tmp

なお、

  • .DS_Store
  • .git
  • npm-debug.log
  • node_modules

あたりは、デフォルトで外されるので、いちいち書かなくてOKです。

.gitignore

npmの話というよりもgit一般の話ですが、.npignore に合わせてこちらも設定しておきます。

.DS_Store
npm-debug.log
node_modules

tmp

.travis.yml

Travis CIは、GitHubにプッシュすると自動的にテストをかけてくれるサービスです。.travis.ymlがその設定ファイルにあたります。テストを書くのは後半に回しますが、とりあえずこれだけ書きます。GitHubに上がっているリポジトリだと、ほぼ必ず Build Status みたいのがついてますが、テストをパスしているとこれが緑(passing)になっていて、カッコイイ...もとい安心感があります。

travis.yml
language: node_js
node_js:
  - 0.10

2時間目

いよいよ、実装です。index.jsにガシガシ書いていきます。合わせて、テストをtestディレクトリに作っていきます。

  • index.js
  • test/

index.js

よくあるパターンは、こんな感じです。必要なモジュールをrequireして、module.exportsの中に実際のコードを書いていきます。実装についての詳細は、ここでは略。

var spawn = require('child_process').spawn,
    through = require('through2'),
    gutil = require('gulp-util'),

module.exports = function(options){
  ...
}

テスト・テスト・テスト

今回は、mochaを使いました。

testディレクトリの構成はこんな感じ。

  • expect/
    • test1.txt
    • test2.txt
  • fixtures/
    • test1.js
    • test2.js
  • main.js (あるいは、main.coffee)

main.jsというか、main.coffeeにテストを書き書き。

main.coffee
should = require 'should'
phantom = require '../'

describe 'gulp-phantom', () ->
  describe 'phantom()', () ->
    it 'should pass file when it isNull()', (done) ->
      ...
    it 'should emit error when file isStream()', (done) ->
      ...
    it 'should trim newline at EOF', (done) ->
      ...

テストがだいたい書けたら、package.jsonにテストスクリプトを指定しておきます。

package.json
{
  "scripts": {
    "test": "mocha -R spec"
  }
}

ちなみに、テストをCoffeeScriptで書く場合は、--compilers--requireの指定が必要です。

package.json
{
  "scripts": {
    "test": "mocha --compilers coffee:coffee-script --require coffee-script/register -R spec"
  }
}

これで、下記のコマンドでテストが実行できるようになります。Travis CIもこの設定を認識してくれます。

$ npm test

注・ハマりかけたところ

実は、この段階ではテストが通ったのですが、Travis CIで引っかかりました (泣)。mochaのタイムアウトだったので、describe のところでタイムアウト値を多めに設定して、事無きを得ました。

main.coffee
describe 'gulp-phantom', () ->
  describe 'phantom()', () ->
    @timeout 10000

3時間目

テストを含めて実装ができたら、READMEやLICENSEを用意して、GitHubに公開する準備をします。

  • LICENSE
  • README.md

この2ファイルを用意したら、

  • GitHubに公開
  • Travis CIを設定
  • npmに公開

で、完成!

LICENSE

MITライセンスにしたので、こんな内容を入れておきます。全文はここにあるので、コピーしてきて、年と名前を差し替えればOK。

The MIT License (MIT)

Copyright (c) 2014 Tsutomu Kawamura

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, ...(略)

README.md

README.md
# gulp-phantom

A PhantomJS plugin for [gulp](https://github.com/wearefractal/gulp).

(略)

GitHubに公開

新しいリポジトリを作って、そこにソースコードをプッシュします。今回用意したのはこちら

Travis CIを設定

アカウントを作っていない場合は、Travis CIにGitHubアカウントを使ってサインアップします。自動的に自分のリポジトリがリストアップされるので、該当するもののスイッチをONにします。作業としては本当にこれだけ。

TravisはGitHubにプッシュされたことをフックにして、自動実行されるので、README.md にビルドバッジ Build Status を足してプッシュしてみます。

README.md
# gulp-phantom [![Build Status](https://travis-ci.org/cognitom/gulp-phantom.svg?branch=master)](https://travis-ci.org/cognitom/gulp-phantom)

A PhantomJS plugin for [gulp](https://github.com/wearefractal/gulp).

(略)

しばらくすると、テストが始まります。「passing」になればOK!

npmに公開

ここからは、あと「3分」です。ぜひ、fnobiさんによる「3分でできるnpmモジュール」をどうぞ。

概略としては、サインアップして、

$ npm adduser

それから、モジュールのフォルダでnpm publishすればOK。

$ npm publish

あとは、別プロジェクトから、npm install <モジュール名>できるかチェックしておきましょう。

放課後

本筋から離れるものの、関連する話題をメモ。

npmで公開しないシャイなモジュール

いきなりnpmに公開するのは、ちょっと抵抗があったり、なかったり。npmでは、ローカルで開発中のモジュールも、ファイルパスを指定すればインストールできます。ただ、この方法だと--save-devできません。

$ npm install /path/to/dir

GitHub上に公開する必要がありますが、gitのURLを指定することもできます。この場合は--save-devが使えます。

$ npm install git://github.com/cognitom/gulp-phantom.git --save-dev

package.json に直接書く場合はこんな感じ。詳しくは、npm-installのドキュメントをどうぞ。

{
  "devDependencies": {
    "gulp": "*",
    "gulp-phantom": "git://github.com/cognitom/gulp-phantom.git"
  }
}

参考