はじめに: jQueryプラグインの公開は「The jQuery Plugin Registry」から「npm」へ

jQueryのプラグイン登録ページ『The jQuery Plugin Registry』にアクセスすると、以下の記載があります。 We recommend moving to npm, using “jquery-plugin” as the keyword in your package.json. The npm blog has instructions for publishing your plugin to npm.

翻訳すると、『package.jsonの”keywords”に「jquery-plugin」を記入して、npmに移ることをお勧めします。npmのブログではプラグインをnpmに公開するための説明があります。』となっています。

つまり自作したjQueryプラグインを世の中に公開したい場合は、これからは「npmに登録しましょう」ということになります。

そこでnpmで公開するのであれば、やっておきたいのが今回紹介するnpmパッケージ（CommonJSモジュール）化です。npmパッケージにしておくことで、Node.js上での開発に取り込んでもらえるようになります。プロジェクト単位での管理が行え、様々なJSのツールを使って迅速な開発が行えるようになります。

今回の投稿はnpmのブログで投稿された以下の記事を元に書いていきます。翻訳して書いている部分もあるので、日本語がたまにおかしいかもしれませんが、予めご了承ください。

• The npm Blog — Making your jQuery plugin work better with npm tools
• The npm Blog — Publishing your jQuery plugin to npm, the quick and dirty way

また、今回の記事はNode.jsとnpmがインストールされていることが前提となっています。まだインストールしていない場合は、以下を参考にしてください。

• Mac OS X Mountain LionにNode.jsとnpmをHomebrewを使ってインストールする – maesblog

package.jsonの対応

npmに公開するためには、まずpackage.jsonファイルが必要です。package.jsonはプロジェクトにおける様々なメタデータを保持し、プロジェクトのパッケージを管理するために使われるファイルとなります。

前提としてnpm公開のjQueryプラグインを使用するには

jQueryプラグインをnpm経由で使用するには、Browserifyやparcelifyなどのnpmパッケージをひとつのファイルにバンドルし、ブラウザで使えるようにしてくれるツールを使います。詳細は当ブログの以下の記事をご参照ください。

• npmで公開されているjQueryプラグインを使う with Browserify & parcelify – maesblog

これらのツールを使う際は、jQueryプラグインを使用するWebアプリ側のpackage.jsonに以下のようにjQueryプラグインのjsファイルとcssファイルのパスを書いておけば、Browserifyやparcelifyにそれぞれのファイルの場所を知らせることができます。

"browser": {
  "example": "./node_modules/example/src/bundle.js"
},
"style": [
  "./node_modules/example/src/bundle.css"
]

jQueryプラグイン側のpackage.jsonの準備

しかし、jQueryプラグインをアップデートしていく中で、ファイルやディレクトリの場所に変更などがあった場合、アプリ側のpackage.jsonの内容も変更しなければならず、メンテナンスが大変です。

そこで、jQueryプラグイン側のpackage.jsonに予めjsファイルやcssファイルのパスを記入しておくようします。（そうすることで、アプリ側のpackage.json側にはjQueryプラグインのjsファイルやcssファイルのパスを書く必要がなくなります。）

package.jsonファイルは、以下のコマンドを実行すると、コマンドを実行したディレクトリ内に作成されます。

[npm init]コマンドを使うと質問形式でpackage.jsonファイル内に項目が作られていきます。作られた項目の中で“name”と“version”は、npmに公開する上で必須の項目となっているので、消さないようにしましょう。

jsファイルのパスの記入

jsファイルのパスは、jQueryプラグイン側のpackage.jsonの”main”の値として記入します。ただし複数のファイルパスは書けないので、複数のjsファイルがある場合は、連結して一つのファイルにするか、モジュール化して複数のファイルを読み込めるようにしておきます。

cssファイルのパスの記入

cssファイルのパスは、jQueryプラグイン側のpackage.jsonの”style”の値として記入します。

"style": [
  "./dist/bundle.css"
]

こちらは複数のcssファイルのパスを書くことができます。例えば、以下のように「*（アスタリスク）」を使って、ルートディレクト内にあるcssファイルをすべてバンドルさせるようにすることもできます。

「jQueryプラグイン」としてキーワードに登録する

package.jsonの“keywords”に「jquery-plugin」を記入しておくと、jQueryプラグインとして見つけてもらいやすくなります。

以下は”keywords”に「jquery-plugin」が記入されているパッケージの一覧となります。

• Browse by Keyword: “jquery-plugin” – npm

jQueryプラグインにCommonJSとの互換性を持たせる

jQueryプラグインをnpmで公開するには、ブラウザ外でも使えるようにしておく必要があります。サーバー上で使う際に、他のモジュールのインポート、他のモジュールへエクスポートできるようCommonJSと互換性を持たせるようにしておきます。

オリジナルのjQueryプラグイン

ベースとなるjQueryプラグインは即時関数（IIFE）で囲んでいるスタイルとします。即時関数が実行されると、グローバルのjQueryオブジェクトが即時関数の中に引き渡されるようになっています。このスタイルを変更し、CommonJSとの互換性を持たせるようにしていきます。

(function($, window, document, undefined) {
    // ここにjQueryプラグインを追加する
　　// ※渡されたjQueryオブジェクトにプラグインのメソッドを追加される
})(jQuery, window, document);

CommonJSと互換性を持たせるには、「jQueryオブジェクトをどう渡すか」、ここが肝になってきます。UMD（the Universal Module Definition）を使えば、CommonJS環境でもAMD環境でもブラウザ環境でも動くようにjQueryオブジェクトを渡せるようになります。ただnpmのブログでは、これから以下で説明していくより簡易的な方法が紹介されていました。

jQueryプラグインが動く環境を検出する

この方法では、jQureyプラグインが使われる環境が、Node.js（CommonJS）やBrowserifyなどで実行できる「module.exports」をサポートしているかどうか（つまりCommonJSをサポートしているかどうか）だけのチェックを行い、jQueryオブジェクの渡し方を切り分けるようにしています。

if (typeof module === "object" && typeof module.exports === "object") {
  // CommonJS版のjQueryを使ったjQueryプラグインが動く
} else {
  // グローバルのjQueryオブジェクトを使ったjQueryプラグインが動く
}

即時関数でラッピング

オリジナルのjQueryプラグインにjQueryオブジェクトを渡すために、上記の条件分岐を組み込んでいきます。

オリジナルのjQueryプラグインと上記の条件分岐を即時関数で囲みます。その引数にjQueryプラグインを代入するためのfactory変数をセットし、即時関数が実行されたら、環境を判別してfanctory変数（つまりjQureyプラグイン）を実行するようにします。

factory変数（つまりjQureyプラグイン）には、その時の環境に応じて「requireを使ったモジュールシステム経由のjQueryオブジェクト」か「グローバルのjQueryオブジェクト」のどちらかが渡されます。

ちょっとわかりにくいと思いますので、詳しくは以下のコードとコメントを見てください。

// この関数（function）は即時に呼び出されます。2つ目の関数（function）は
// 引数のfactoryを通してこの関数に渡されます。
(function (factory) {
  // もしmodule変数があり、それがexportsプロパティを持っていれば、
  // Nodeライクな環境で動きます。moduleシステムが使用しているjQueryオブジェクトを
  // ロードするようrequireし、中に渡してください。
  if (typeof module === "object" && typeof module.exports === "object") {
    // モジュールにjQueryプラグインへの直接参照を持たせます。
    module.exports = factory(require("jquery"), window, document);
  }
  // そうでなけば、ブラウザー上で動くので、グローバルなjQueryオブジェクトを中に
  // 渡してください。
  else {
    factory(jQuery, window, document);
  }
} (function ($, window, document, undefined) {
  // ここのコードは上の関数からどんなjQueryオブジェクトが渡されても受け取り、
  // jQueryプラグインをjQueryオブジェクトにくっつけます。
}));

実際に上記のフォーマットで作ったjQueryプラグインをサンプルとして以下に紹介しておきます。参考にしてください。

• [サンプル] jQuery.cbiframesize.js

package.jsonの対応

最後に、上記でjQueryオブジェクトを「require」しているので、「package.json」に依存関係を追記しておきます。

"dependencies": {
  "jquery": "^2.1.3"
}

これで、CommonJSと互換性を持ったjQueryプラグインができあがりです。次は、作ったjQueryプラグインをnpmに公開する方法を紹介していきます。

jQueryプラグインをnpmに公開する

jQueryプラグインをnpmに公開する方法は、以下のnpmが用意している動画を見れば、英語ですがだいたい理解できると思います。それを踏まえて説明していきたいと思います。

npmへユーザー登録する

npmで、今回説明しているjQeryプラグインのようなパッケージを公開するには、npmへのユーザー登録が必要となります。まず、自分がnpmのユーザーかどうか以下のコマンドで調べます。

$ npm whoami

npmへのユーザー登録がなければ、「[npm adduser]コマンドを実行しなさい」と結果が返されます。

$ npm whoami
Not authed.  Run 'npm adduser'

[npm adduser]コマンドを実行して、ユーザー登録を行います。質問形式で「ユーザ名」、「パスワード」、「（公開用）メールアドレス」が聞かれるので、それぞれ入力していきます。

$ npm adduser
Username: ユーザー名
Password: パスワード
Email: (this IS public) メールアドレス

ユーザー登録が済んだら、[npm login]コマンドを実行して、クライアント側に証明書を記録させます。

$ npm login
Username:
Password:
Email: (this IS public)

証明書がクライアント側に登録されていることを確実にするために[npm config ls]コマンドを実行します。

$ npm config ls
; cli configs
user-agent = "npm/2.1.7 node/v0.10.33 darwin x64"

; userconfig /Users/maeda/.npmrc
//registry.npmjs.org/:_password = "czUzNTZhYWFucG0="
//registry.npmjs.org/:always-auth = false
//registry.npmjs.org/:email = "xxxx@xxxx.xx"
//registry.npmjs.org/:username = "xxxxxxxxx"

; builtin config undefined
prefix = "/usr/local"

; node bin location = /usr/local/bin/node
; cwd = /Applications/xxxx/xxxxx/xxxx
; HOME = /Users/maeda
; 'npm config ls -l' to show all defaults.

npmへのユーザー登録はこれで完了です。

jQueryプラグインをnpmに公開する

npmへのユーザー登録が済んだら、パッケージを公開することができるようになります。公開するパッケージのディレクトリに移動して、[npm publish]コマンドを実行するとnpmにパッケージが公開されます。上でも触れたように、package.jsonの“name”と“version”は必須なので、記載がない場合はエラーとなります。（また、nameに大文字が含まれている場合やversionに変更がない場合などもエラーが出ます。）

$ npm publish

package.jsonに設定してある“name”の値がパッケージ名として登録されます。”name”の値に使える文字は「小文字英数字とハイフン」のみとなるので注意してください。また他のパッケージと重複しない名前をつける必要があります。問題なければ、以下のURLで公開されます。

http://npmjs.com/package/パッケージ名

自分の作成したjQueryプラグインも公開してみました。

$ npm publish
+ jquery-cbiframesize-js@1.0.3

以下のようにnpmに公開されます。

• https://www.npmjs.com/package/jquery-cbiframesize-js

npmに公開したjQueryプラグインのアップデート

jQueryプラグインに変更を加えた場合、「npm version」コマンドでpackage.jsonの”version”の値（バージョン数）を変更します。

$ npm version [<newversion> | major | minor | patch | prerelease | preminor | premajor ]

「npm version」コマンドについては以下のブログの記事が参考になります。

• npmのあまり知られてない機能 10選 – from scratch

package.jsonの”version”の値を変更したら、公開の時と同じ[npm publish]コマンドでアップデートを行います。

$ npm publish

• 11 – Publishing npm packages | npm Documentation

まとめ

だいぶ長くなりましたが、以上がjQueryプラグインをCommonJSモジュール化して、npmに公開するまでの方法となります。最低でもpacakege.jsonファイルさえ用意すれば、npmに公開することはできますが、やはりCommonJS化してNode.jsでの開発でも安心して使ってもらえるようにしておきたいものです。

今回の投稿は、複数のブログ記事のツギハギツギハギな感じで、あまりうまくまとめられませんでしたが、少しでもjQueryプラグイン作者のみなさんの役に立てれば幸いです。