元の TypeScript ソースまでたどれるソースマップを伴う、JavaScript ファイルの Bundle & Minify 化の方法

前提条件

Visual Studio (Visual Studio Code ではなく)上での Webアプリ開発、とくに TypeScript によるクライアント側スクリプト実装の話。

現在自分が抱えているプロダクトでは、TypeScript から JavaScript への変換は、1つの .ts ファイルにつき 1つの .js ファイルを生成する構成 ― プロジェクト内の .ts ファイル群からひとつの .js ファイルを生成するのではなく ― としている。

そしてこれら .ts から変換した .js ファイル群は、所定のグループごとに、ファイルサイズ削減を目的とした縮小化(Minify) を適用し、かつ、ひとつの .js ファイルへの単一化 (Bundle) を実施している。

Bundle & Minify を実施する具体的な手順としては、ASP.NET MVC が備える Bundle & Minify 機能 (Web アプリ実行時に動的に Bundle & Minify される)、ないしは、Visual Studio 拡張の「Bundle & Minifier」を使ってきた。

これまで実現できていなかったこと

だがしかし、この構成でひとつだけあきらめていたことがあった。

それは Bundle & Minify 化された JavaScript コードからの、
いちばん大元の TypeScript ファイルへたどることのできる
ソースマップファイル (.map) の生成
である。

TypeScript コンパイラは当然のことながら、.map ファイルを生成することができる。
実際、自分のプロダクトでも .map ファイルを生成するよう tsconfig.json を構成してある。

しかし前述の Bundle & Minify 化の手法だと、その Bundle & Minify 処理過程で新たに生成される .map ファイルは、Bundle & Minify 前の JavaScript コードにたどれるまでとなる。
TypeScript ソースコードにまで到達しないのだ。

なくてもどうにかならなくもないけど...

もっとも TypeScript コンパイラが生成する JavaScript コードは、元の TypeScript コードと割と一対一で対応してたりする。
なので、Bundle & Minify 前の JavaScript コードにまで到達できれば、人力的探索で TypeScript ソースコードまでたどれなくもない。

また、IDE やブラウザが備えるデバッガ上で TypeScript ソースコード上でブレークポイントを張ったりしたいときも、実行時と開発時とで、HTML 上で読み込む JavaScript ファイルを違える工夫で回避できる。
つまりは、開発時は Bundle & Minify 前の JavaScript ファイル ― これには TypeScript コンパイラが生成した .map ファイルがついている ― を HTML で読み込むように、実行時とは構成を変更できるようにするのだ。

しかしそうはいっても、クラッシュ通知が来てるときに、そのスタックトレースが元の TypeScript コードにおけるソース行を直接指していないとなると、気分が焦っているのに余計な手間がかかって何とも煩わしい。


そこで重い腰を上げて、Bundle & Minify 化するときに TypeScript ソースコードまでたどれる .map ファイルを生成する方法はないものか、調べてみることにした。

Gulp 使えば楽勝だった!

あれこれ検索したり試行錯誤を繰り返してる中で、Node.js 上で動作するタスク自動化ツールのひとつ、Gulp を使えばあっさり実現できることがわかった。

以下はその手順である。

必要なツールやパッケージのインストール

Node.js のパッケージマネージャ、npm を使って、まずはプロジェクトフォルダ上で Gulp をインストール。

>npm init

...(package.json 新規作成のためにあれこれ問いに応答する)...

>npm install --save-dev gulp

さらに、

• Gulp を使ってファイルを結合、つまり Bundle を実施するために gulp-concat、
• 難読化を伴う JavaScript コードの縮小化のために gulp-uglify、
• いくつかの並行タスクを束ねるために merge-stream、
• そして今回の命題のキモとなる、ソースマップの生成のために gulp-sourcemaps

を続けてインストールする。

>npm install --save-dev gulp-concat

>npm install --save-dev gulp-uglify

>npm install --save-dev merge-stream

>npm install --save-dev gulp-sourcemaps

Bundle & Minify の設定ファイル

そして話が前後するが、前述の Visual Studio 拡張にて Bundle & Minify 化するときに、どの JavaScript ファイルを Bundle & Minify するのかの設定ファイルとして、bundleconfig.json という JSON 形式のファイルで記述してある (内容は下記のような感じ)。

[

{

  "outputFileName": "lib.min.js",

  "inputFiles":[

  "lib/**/*.js

  ]

},

{

  "outputFileName": "bundle.min.js",

  "inputFiles":[

  "src/**/*.js

  ]

}

]

gulpfile.js の作成 - まずは最低限 Bundle & Minify するところまで

前述の bundleconfig.json を読み込んで Bunlde & Minify するよう、gulpfile.js を組んでみる。
ソースマップ生成は抜きにしてまずは Bundle & Minify ができるところまでだと、こんな感じだ。

var gulp = require('gulp');

var concat = require('gulp-concat');

var uglify = require('gulp-uglify');

var merge = require('merge-stream');



// bundleconfig.json の内容を読み込む

var bundleconfig = require('./bundleconfig.json');



gulp.task('min:js', function () {

  // bundleconfig.json の記述から1要素ごとに、

  // Bunlde & Minify 化のタスクに射影する

  var tasks = bundleconfig.map(function (bundle) {

    var task = gulp.src(bundle.inputFiles, { base: "." })

      .pipe(concat(bundle.outputFileName)) // concat で連結(Bundle)

      .pipe(uglify())                      // uglify で難読&縮小化(Minify)

      .pipe(gulp.dest("."));

    return task;

  });

  // それらタスクを束ねて返して実行

  return merge(tasks);

});

ここまでの状態で、プロジェクトフォルダをカレントディレクトリとしたコマンドプロンプト上で「.\node_modules\.bin\gulp min:js」などと実行すると、bundleconfig.json の指定に従って Bundle & Minify 化が実行されるはずだ。

ただしここまでの記述ではまだ、ソースマップは生成されない。

ソースマップ生成

ではいよいよ、ソースマップの生成を組み込む。

単に Bundle & Minify 前のソースコードまでたどれるだけであれば、ネットで検索したときによく見かける下記の記述 (太字の箇所) を書き足せばよい。

var gulp = require('gulp');

...

var sourcemaps = require('gulp-sourcemaps');

...

gulp.task('min:js', function () {

  // bundleconfig.json の記述から1要素ごとに、

  // Bunlde & Minify 化のタスクに射影する

  var tasks = bundleconfig.map(function (bundle) {

    var task = gulp.src(bundle.inputFiles, { base: "." })

      .pipe(sourcemaps.init()) // ソースマップ生成機構を仕掛ける

      .pipe(concat(bundle.outputFileName)) // concat で連結(Bundle)

      .pipe(uglify())                      // uglify で難読&縮小化(Minify)

      .pipe(gulp.dest("."))

      .pipe(sourcemaps.write("./")) // ソースマップを出力

      .pipe(gulp.dest("."));

    return task;

  });

...

だが今回の最終目標は、Bundle & Minify 前のコードまでではなく、さらにその前の TypeScript コードにまでたどれるソースマップの生成だ。

そのために、gulp-sourcemaps に対して、以下の指示を書き足す。

...

    var task = gulp.src(bundle.inputFiles, { base: "." })

      .pipe(sourcemaps.init({loadMaps: true})) // ソースマップ生成機構を仕掛ける

      ...

上記のとおり、gulp-sourcemaps の init メソッド呼び出しの際に、
「{loadMaps: true}」のオプション指定を書き足す
のだ。

こうすることにより、gulp-sourcemaps は、TypeScript コンパイラが生成したソースマップをまずは読み込んで、この情報に基づいて最終的に出力される Bundle & Minify 化された JavaScript コードに対するソースマップを生成するようだ。

つまりここまでの手順の要領で Gulp による Bundle & Minify タスクを実装すれば、Bundle & Minify 化された JavaScript コードを開始地点として、いちばんはじめの TypeScript ソースコードにまで到達できるソースマップも同時生成できるのだ。

最後に、watch と Visual Studio 統合も

最後に、.ts ファイルを保存して JavaScript コードが生成・更新されたら、自動で Bundle & Minify も実行されるよう watch タスク (下記) も加えておくとよいだろう。

gulp.task('watch', function () {

  bundleconfig.forEach(function (bundle) {

    gulp.watch(bundle.inputFiles, ["min:js"]);

  });

});

Visual Studio 上の作業と統合するのであれば、Visual Studio のタスクエクスプローラーから設定すればよい。

Visual Studio のタスクエクスプローラーを開けば、ここまでで gulpfile.js に記述した「min:js」タスクと「watch」タスクが自動検出されてツリーに見えているはずだ。
あとは、
-「min:js」タスクをビルド後に実行するタスクに、
-「watch」タスクをプロジェクト読み込み後に実行するタスクに、
割り当てるなどしておくとよいだろう。

以上で、クラッシュ時スタックトーレスやデバッガ上での実行において、Bundle & Minify 化した JavaScript コードが読み込まれている場合でも、大元の TypeScript ソースコードに基づいて取り扱うことができる、快適な環境を構築できた。

※上記に加えて、後日の投稿である "AngularJS の依存性注釈の自動生成" も組み込んだコード全体は こちらの gist に置いてある。