module import できない古典的な jQuery 拡張を、import できるようにする

前回の記事で、下記のように JavaScript のモジュール機構をまったく知らない世代の実装となっている jQuery 拡張ライブラリについて、(function ($) {
// こうすることで jQuery に拡張機能 xxxx を括り付ける
$.fn.xxxx = ...
})(jQuery);これを webpack + TypeScript の開発環境にてどうやって使うか、その方法について投稿した。
前回の作戦は、「jQuery をバンドル対象外」とするよう webpack を構成することで、jQuery オブジェクトをグローバル名前空間に晒すこととし、その結果、旧来どおり script タグで jQeury を読み込むようになったので、レガシーな jQuery 拡張も使えるようになるよ、というものであった。

いっぽうで、このレガシーな jQuery 拡張の実装のほうに手を入れることで、その jQuery 拡張を module import 可能に対応させることで先の命題を解決することもできる。

今回はその方法について説明する。

レガシー jQuery 拡張をモジュールバンドルすると実行時エラーが起きる仕組み

さて、レガシー jQuery 拡張ライブラリが、実行時に「ReferenceError: jQuery is not defined (jQuery というシンボルが見つからない)」エラーを引き起こすのは、レガシー jQuery 拡張ライブラリが、グローバル名前空間に "jQuery" というシンボルが存在することを前提としているためだ (下記参照)。(function ($) {
$.fn.xxxx = ...
})(jQuery); // <- ここいっぽうで、webpack を用いて CommonJS 方式でモジュールバンドルする際は、jQuery 本体もモジュール機能で名前空間が隔離されている。
結果、グローバル名前空間に "jQuery" という名前で jQuery オブジェクトをさらすことはない。

この食い違いが原因で、レガシー jQuery 拡張は実行時に "jQuery というシンボルが見つからない" エラーを引き起こすわけである。

CommonJS の仕組みにおいては、jQuery オブジェクトに用事があるモジュールは、そのモジュール内で "require('jquery')" を実行してその戻り値としての jQuery オブジェクトを使用する必要がある。

解決方法

ここまでわかれば、レガシー jQuery 拡張を CommonJS モジュール対応させるのは簡単だ。

グローバル名前空間にある jQuery シンボルを参照しようとするのをやめ、代わりに require('jquery') で jQuery モジュールを正規にインポートしたものを参照すればよい。(function ($) {
$.fn.xxxx = ...
})(require('jquery')); // グローバル変数 jQuery ではなく、
// require() の結果を引数に渡す!これで webpack + TypeScript な構成でも、この改造後の jQeuery 拡張を import しモジュールバンドルできるようになる。

下位互換も維持するには

なお、このような改造を施した jQuery 拡張ライブラリは、今度は、旧来どおり素で script タグでブラウザに読み込ませるような構成だと動作しないことになる。

script タグで個々の JavaScript ライブラリを読み込ませるような構成だと、ブラウザの JavaScript エンジン上では require などという CommonJS モジュール機構が存在しないので、ここで実行時エラーになるわけだ。

最初の話と逆転しているわけである。

ただし、jQuery 本体それ自体が、CommonJS 方式のモジュール機構にも、素の script タグで読み込ませるケースにも、両方に対応できていることからわかるように、今回話題にしてるようなレガシー jQuery 拡張も、両方のケースに対応させることは難しくない。

アルゴリズムとしては、下記のとおりだ。

1. まず、(jQuery拡張) 自身が読み込まれた環境が CommonJS モジュール機構内かどうかを判定し、
2. モジュール機構内であれば、require('jquery') を実行して戻り値で返ってきたオブジェクト ( = jQuery オブジェクト) を、
3. そうでなければグローバル名前空間の jQuery というシンボルを使って、
4. jQuery 拡張機能を括り付ける

実際にコードに書き表したのが下記である。// 下記赤文字の jQuery 拡張機能を括り付ける関数を引数 factory として受け取り...
(function (factory) {
// 先述のアルゴリズムで jQuery オブジェクトの参照方法を if 文で仕分けて、
// 引数 factory で受け取った jQuery 拡張機能括り付け関数を実行する。

// ...という処理を無名関数として実装、即時実行する。

// CommonJS の場合...
if (typeof exports == 'object' && typeof module == 'object') {
// require('..') で取得したオブジェクト (= jQuery オブジェクト) を渡す
factory(require('jquery'));
}

// ブラウザの場合...
else {
// グローバル変数 jQeury を渡す
factory(jQuery);
}
})(function ($) { // jQuery 拡張を括り付ける本体
// ちなみに、この関数内は改造の必要はない。
$.fn.xxxx = ...
})CommonJS を知らないレガシーな jQuery 拡張機能であっても、このような改造を施せば、旧来通りの使い方もできる下位互換を維持しつつ、webpack による CommonJS モジュールバンドリングにも使用できるようになる。

補足

ちなみにこの実装方法は、カラーピッカーとして (多分) 有名な jQuery 拡張である Spectrum のソースコードを参照してて知った。

Spectrum のソースコードでは、JavaScript のモジュール機構として、CommonJS のみならず、AMD 方式にも対応しており、ブラウザう + CommonJS + AMD の 3方式すべてに互換となっている。詳しくは Spectrum のソースコードを参照されたし。