npmでは先月よりjQueryコミュニティのサポートを開始しました。そのニュースを受けて前回の投稿『npmで公開されているjQueryプラグインを使う with Browserify & parcelify』では、Webアプリを開発する際に、npmで公開されているjQueryプラグインを使用する方法を紹介しました。いわばWebアプリ開発者向けの記事でした。今回はjQueryプラグインの作者向けの記事となります。実際に開発されているjQueryプラグインをnpmに公開する方法をご紹介します。
はじめに: 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がインストールされていることが前提となっています。まだインストールしていない場合は、以下を参考にしてください。
package.jsonの対応
npmに公開するためには、まずpackage.jsonファイルが必要です。package.jsonはプロジェクトにおける様々なメタデータを保持し、プロジェクトのパッケージを管理するために使われるファイルとなります。
前提としてnpm公開のjQueryプラグインを使用するには
jQueryプラグインをnpm経由で使用するには、Browserifyやparcelifyなどのnpmパッケージをひとつのファイルにバンドルし、ブラウザで使えるようにしてくれるツールを使います。詳細は当ブログの以下の記事をご参照ください。
これらのツールを使う際は、jQueryプラグインを使用するWebアプリ側のpackage.jsonに以下のようにjQueryプラグインのjsファイルとcssファイルのパスを書いておけば、Browserifyやparcelifyにそれぞれのファイルの場所を知らせることができます。
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”の値として記入します。
こちらは複数のcssファイルのパスを書くことができます。例えば、以下のように「*(アスタリスク)」を使って、ルートディレクト内にあるcssファイルをすべてバンドルさせるようにすることもできます。
「jQueryプラグイン」としてキーワードに登録する
package.jsonの“keywords”に「jquery-plugin」を記入しておくと、jQueryプラグインとして見つけてもらいやすくなります。
以下は”keywords”に「jquery-plugin」が記入されているパッケージの一覧となります。
jQueryプラグインにCommonJSとの互換性を持たせる
jQueryプラグインをnpmで公開するには、ブラウザ外でも使えるようにしておく必要があります。サーバー上で使う際に、他のモジュールのインポート、他のモジュールへエクスポートできるようCommonJSと互換性を持たせるようにしておきます。
オリジナルのjQueryプラグイン
ベースとなるjQueryプラグインは即時関数(IIFE)で囲んでいるスタイルとします。即時関数が実行されると、グローバルのjQueryオブジェクトが即時関数の中に引き渡されるようになっています。このスタイルを変更し、CommonJSとの互換性を持たせるようにしていきます。
CommonJSと互換性を持たせるには、「jQueryオブジェクトをどう渡すか」、ここが肝になってきます。UMD(the Universal Module Definition)を使えば、CommonJS環境でもAMD環境でもブラウザ環境でも動くようにjQueryオブジェクトを渡せるようになります。ただnpmのブログでは、これから以下で説明していくより簡易的な方法が紹介されていました。
jQueryプラグインが動く環境を検出する
この方法では、jQureyプラグインが使われる環境が、Node.js(CommonJS)やBrowserifyなどで実行できる「module.exports」をサポートしているかどうか(つまりCommonJSをサポートしているかどうか)だけのチェックを行い、jQueryオブジェクの渡し方を切り分けるようにしています。
即時関数でラッピング
オリジナルのjQueryプラグインにjQueryオブジェクトを渡すために、上記の条件分岐を組み込んでいきます。
オリジナルのjQueryプラグインと上記の条件分岐を即時関数で囲みます。その引数にjQueryプラグインを代入するためのfactory変数をセットし、即時関数が実行されたら、環境を判別してfanctory変数(つまりjQureyプラグイン)を実行するようにします。
factory変数(つまりjQureyプラグイン)には、その時の環境に応じて「requireを使ったモジュールシステム経由のjQueryオブジェクト」か「グローバルのjQueryオブジェクト」のどちらかが渡されます。
ちょっとわかりにくいと思いますので、詳しくは以下のコードとコメントを見てください。
実際に上記のフォーマットで作ったjQueryプラグインをサンプルとして以下に紹介しておきます。参考にしてください。
- [サンプル] jQuery.cbiframesize.js
package.jsonの対応
最後に、上記でjQueryオブジェクトを「require」しているので、「package.json」に依存関係を追記しておきます。
これで、CommonJSと互換性を持ったjQueryプラグインができあがりです。次は、作ったjQueryプラグインをnpmに公開する方法を紹介していきます。
jQueryプラグインをnpmに公開する
jQueryプラグインをnpmに公開する方法は、以下のnpmが用意している動画を見れば、英語ですがだいたい理解できると思います。それを踏まえて説明していきたいと思います。
npmへユーザー登録する
npmで、今回説明しているjQeryプラグインのようなパッケージを公開するには、npmへのユーザー登録が必要となります。まず、自分がnpmのユーザーかどうか以下のコマンドで調べます。
npmへのユーザー登録がなければ、「[npm adduser]コマンドを実行しなさい」と結果が返されます。
[npm adduser]コマンドを実行して、ユーザー登録を行います。質問形式で「ユーザ名」、「パスワード」、「(公開用)メールアドレス」が聞かれるので、それぞれ入力していきます。
ユーザー登録が済んだら、[npm login]コマンドを実行して、クライアント側に証明書を記録させます。
証明書がクライアント側に登録されていることを確実にするために[npm config ls]コマンドを実行します。
npmへのユーザー登録はこれで完了です。
jQueryプラグインをnpmに公開する
npmへのユーザー登録が済んだら、パッケージを公開することができるようになります。公開するパッケージのディレクトリに移動して、[npm publish]コマンドを実行するとnpmにパッケージが公開されます。上でも触れたように、package.jsonの“name”と“version”は必須なので、記載がない場合はエラーとなります。(また、nameに大文字が含まれている場合やversionに変更がない場合などもエラーが出ます。)
package.jsonに設定してある“name”の値がパッケージ名として登録されます。”name”の値に使える文字は「小文字英数字とハイフン」のみとなるので注意してください。また他のパッケージと重複しない名前をつける必要があります。問題なければ、以下のURLで公開されます。
http://npmjs.com/package/パッケージ名
自分の作成したjQueryプラグインも公開してみました。
以下のようにnpmに公開されます。
npmに公開したjQueryプラグインのアップデート
jQueryプラグインに変更を加えた場合、「npm version」コマンドでpackage.jsonの”version”の値(バージョン数)を変更します。
「npm version」コマンドについては以下のブログの記事が参考になります。
package.jsonの”version”の値を変更したら、公開の時と同じ[npm publish]コマンドでアップデートを行います。
まとめ
だいぶ長くなりましたが、以上がjQueryプラグインをCommonJSモジュール化して、npmに公開するまでの方法となります。最低でもpacakege.jsonファイルさえ用意すれば、npmに公開することはできますが、やはりCommonJS化してNode.jsでの開発でも安心して使ってもらえるようにしておきたいものです。
今回の投稿は、複数のブログ記事のツギハギツギハギな感じで、あまりうまくまとめられませんでしたが、少しでもjQueryプラグイン作者のみなさんの役に立てれば幸いです。
コメント