型定義もなく module import もできないレガシー jQuery 拡張を、webpack + module import な TypeScript で使う : @jsakamoto

2017年 12月 14日

型定義もなく module import もできないレガシー jQuery 拡張を、webpack + module import な TypeScript で使う

前提

jQuery を使用した Web アプリクライアント側実装における話。

自前のコードは TypeScript で記述し、これをモジュールバンドラーである webpack を使用して、JavScript へのトランスパイルからモジュールバンドルまで実施する構成である。

プロジェクト立ち上げの様子はこうだ。

まず npm (yarn でも可) でプロジェクトを初期化。
> npm init -f -y続けて必要な Node パッケージをインストールする。> npm install --save-dev webpack typescript ts-loader jquery @types/jquerypackage.json はこんな感じ。

{
  "name": "sample-webapp",
  "version": "1.0.0",
  "scripts": {
    "build": "webpack",
    "watch": "webpack -w"
  },
  "devDependencies": {
    "@types/jquery": "^3.2.17",
    "jquery": "^3.2.1",
    "ts-loader": "^3.2.0",
    "typescript": "^2.6.2",
    "webpack": "^3.10.0"
  }
}

次に、TypeScript コンパイラを使用して、既定の tsconfig.json も作成しておく。>.\node_modules\.bin\tsc --initwebpack.cconfig.js も下記のとおり記述する。

// webpack.config.js
module.exports = {
    entry: ['./src/app.ts'],
    output: {
        filename: './wwwroot/js/bundle.js'
    },
    resolve: { extensions: ['.js', '.ts'] },
    module: {
        loaders: [
            {
                test: /\.ts$/, use: [
                    { loader: 'ts-loader' }
                ]
            }
        ]
    },
    devtool: 'source-map'
};

そして、アプリケーションコードとなる ./src/app.ts を作成。

// ./src/app.ts
import * as $ from 'jqeury';

$(() => {
    let randomNum = Math.round(100 * Math.random());
    $('#p1').text(randomNum);
});

以上で、「npm run build」を実行すれば、app.ts が JavScript に変換されつつ、jQuery の JavaScript コードをモジュールバンドルした、"./wwwroot/js/bundle.js" ができあがる。

この bundle.js を HTML コンテンツ中から script タグで参照・読み込むよう記述するわけだ。
(例えば下記 ./wwwroot/index.html のように。)

<html>
<body>
    <p id="p1"></p>
    <p id="p2"></p>
    <script src="/js/bundle.js"></script>
</body>
</html>

命題

さてここで、下記のような実装がされた、クラシカルな jQuery 拡張ライブラリ ( 架空の例として ./wwwroot/js/jquery.fizzbuzz.js ) を使う必要に迫られたとする。

// ./wwwroot/js/jquery.fizzbuzz.js
(function($) {
    $.fn.fizbuzz = function(n) {
        ...
    }
})(jQuery);

先に述べた構成・開発環境において、どうやってこの古典的な jQuery 拡張を使用するのか、というのが本稿の命題だ。

まずは externals 化

このクラシック実装な jQuery 拡張は、上記のとおり、JavaScript のモジュール機構など考慮していない実装なので、app.ts で下記のように

// ./src/app.ts
import * as $ from 'jqeury';
import '../wwwroot/js/jquery.fizz.buzz';

$(() => {
    let randomNum = Math.round(100 * Math.random());
    $('#p1').text(randomNum);
});

と import 文を書き足して参照しても、これは機能しない。

webpack によるビルドは成功するものの、いざブラウザで index.html を開くと「ReferenceError: jQuery is not defined (jQuery というシンボルが見つからない)」という実行時エラーになる。

そこで、まずは webpack の構成を変更し、jQuery が webpack によるモジュールバンドルに取り込まれないようにする。

そして代わりに、jQuery およびクラシック jQuery 拡張ライブラリ ( この例では jquery.fizzbuzz.js ) を、HTML 中から各々 script タグで参照するようにするのだ。

まず webpack.config.js に以下のように externals プロパティを記述する。

// webpack.config.js
module.exports = {
    entry: ['./src/app.ts'],
    output: {
        filename: './wwwroot/js/bundle.js'
    },
    resolve: { extensions: ['.js', '.ts'] },
    module: {
        loaders: [
            {
                test: /\.ts$/, use: [
                    { loader: 'ts-loader' }
                ]
            }
        ]
    },
    devtool: 'source-map',
    externals: {
        "jquery": '$'
    }
};

そして index.html には以下のとおりに script タグを追加する。

<html>
<body>
    <p id="p1"></p>
    <p id="p2"></p>

    <!-- 別途、下記 src 属性で指定されたパスに
    当該 JavaScript ファイルを配置しておくこと -->
    <script src="/js/jquery.min.js"></script>
    <script src="/js/jquery.fizzbuzz.js"></script>

    <script src="/js/bundle.js"></script>
</body>
</html>

この構成は、今回のようなケースに限らず、JavaScript ライブラリを CDN 経由で参照するのでバンドルに含めたくない、といった場合にも採用する構成だ。

これで実行時に jquery.fizzbuzz.js が初期化失敗することはなくなった。

TypeScript における型定義の解決

アプリケーションコードをTypeScript ではなく素の JavaScript で記述していたのであれば、以上、webpack の externals 指定を構成するだけで対応完了となる。

しかし今回の命題では、アプリケーションコードは TypeScript で記述することとしている。
そのため、何らかの手段で拡張された jQuery メソッドの情報を TypeScript に教えてやらないといけない。

今回の架空の例である jquery.fizzbuzz.js は、$("セレクタ").fizzbuzz(数値) という、fizzbuzz メソッドが jQuery に追加になるという代物である。

だが、ここまでの段階ではまだ、app.ts に下記のとおり記述しても、TypeScript のコンパイルが「TS2339: Property 'fizzbuzz' does not exist on type 'JQuery<HTMLElement>'.」というエラーで失敗する。

// ./src/app.ts
import * as $ from 'jqeury';

$(() => {
    let randomNum = Math.round(100 * Math.random());
    $('#p1').text(randomNum);
    $('#p2').fizzbuzz(randomNum); // ← この行がコンパイルエラー
});

TypeScript コンパイラには、jquery.fizzbuzz.js によって fizzbuzz メソッドが増えるということがわからない・知らされていないためだ。

型定義情報を記述

「jQuery に fizzbuzz メソッドが増えている」ことを TypeScript コンパイラに知らしめるためには、型定義を自前で書けばよい。

ということで、./src/jquery.fizzbuzz.d.ts を作成。
単純に jQuery の型定義で提供されている JQuery インターフェース定義に対し、追加の定義を書き足せばよい。

// ./src/jquery.fizzbuzz.d.ts
interface JQuery {
    fizzbuzz(n:number) : jQuery;
}

以上で、TypeScript 型定義もなく、JavaScript モジュール機構にも対応していない古典的な jQuery 拡張ライブラリを、webpack + module import な TypeScript + jQuery の構成でも使用できるようになる。

参考までに、プロジェクト全体を GitHub にサンプルコードとして載せておいた。

こんなクラシックな jQuery 拡張を相手にしないで済むのであれば、それがいちばんよいのだろう。
とはいえ、なかなか現実にはそうもいかないこともあろうかと思う。

そんな場面に遭遇した時には、本稿の手順で対応することを検討するのも選択肢のひとつである。

by developer-adjust | 2017-12-14 23:10 | Web系一般 | Comments(0)

<< module import で...

Visual Studio 上... >>


	ファン申請 ※ メッセージを入力してください

@jsakamoto

型定義もなく module import もできないレガシー jQuery 拡張を、webpack + module import な TypeScript で使う

前提

命題

まずは externals 化

TypeScript における型定義の解決

型定義情報を記述

ファン申請