なぜ「ソースマップ」という黒魔術と向き合う必要があるのか？
やあ、フロントエンド開発の最前線へようこそ。
君たちが普段何気なく書いているTypeScriptのコード。ブラウザが実行する時には、それが綺麗さっぱりJavaScriptにトランスパイルされているよね。ここで一つ、深淵を覗いてみよう。
デバッグ中にブラウザのDevToolsを開いたとき、ブレークポイントが「謎の変換後のJSコード」で止まって絶望したことはないかい？ 「俺は今、どの行をデバッグしているんだ？」という迷宮入りを防ぐための羅針盤、それがソースマップ（Source Map）だ。
今日は、現場で「なんとなく設定している」tsconfig.jsonのソースマップ周りを、プロとして完全に制御する方法を叩き込む。
—
1. ソースマップの設定をマスターする
まずは、`tsconfig.json`の以下の3つのプロパティを整理しよう。
{
“compilerOptions”: {
// 1. ソースマップを別ファイル(.js.map)として出力
“sourceMap”: true,
// 2. ソースマップをJSファイルに埋め込む
“inlineSourceMap”: false,
// 3. 型定義ファイル(.d.ts.map)を生成して、型定義へのジャンプを可能にする
“declarationMap”: true
}
}
なぜこの使い分けが重要なのか？
- `sourceMap: true` (基本にして最強)
実務ではこれがデフォルトだ。`.js`ファイルと対になる`.js.map`を生成する。ブラウザはJSを読み込む際、末尾にある `//# sourceMappingURL=…` を見つけて、このファイルを裏側でフェッチする。これにより、ソースコードの行番号と元のTSファイルが完璧にマッピングされる。
- `inlineSourceMap: true` (禁断の果実)
ソースマップ自体をbase64エンコードしてJSファイルの中にぶち込む設定だ。HTTPリクエストが1回減るメリットはあるが、JSファイルが肥大化する。本番環境でこれをやるとJSのサイズが激増してパフォーマンスが悪化するから、基本的には開発用だ。
- `declarationMap: true` (ライブラリ開発者のたしなみ)
もし君がnpmライブラリを公開しているなら、これは必須だ。これがないと、利用者が君の型定義ファイル(`index.d.ts`)に「定義へ移動」したとき、どこで型が定義されたのか追跡できなくなる。DX（開発者体験）を極めたいなら、迷わず `true` にしよう。
—
2. ブラウザは裏側で何をしているのか？
ブラウザのDevToolsを開いて「Sources」タブを見てほしい。あそこで君が見ているTypeScriptファイルは、実はブラウザがソースマップを使って「復元」したものなんだ。
1. ブラウザはJSファイルをダウンロードする。
2. JSの末尾にある `sourceMappingURL` を見つける。
3. そこから `.map` ファイルをダウンロードする。
4. `.map` ファイルの中にある「行・列の変換テーブル（Mapping）」を参照する。
5. ブラウザが持っているJSの実行エンジン上の位置と、元のTSの行番号を紐付けて表示する。
この一連の流れがあるからこそ、我々はブラウザ上でTSのままデバッグできる。もし君が「ソースマップが効かない！」と叫ぶときは、大抵このパスがずれているか、そもそもビルド生成物とマップファイルが一致していない時だ。
—
3. 実践：現場で使えるtsconfig.jsonテンプレート
現場で混乱を避けるために、環境ごとに設定を使い分けるのがプロの流儀だ。以下は実務でそのまま使える構成案だ。
{
“compilerOptions”: {
“target”: “ESNext”,
“module”: “ESNext”,
// — 開発時（ローカル）の設定 —
// 外部ファイルに出力して、読み込み負荷を分散させる
“sourceMap”: true,
“inlineSourceMap”: false,
// ライブラリ開発やモノレポ環境なら必須
“declaration”: true,
“declarationMap”: true,
// — さらに知見を深めるためのTips —
// ソースコード本体もマップに埋め込むと、ソースファイルが見当たらない事故を防げる
// “inlineSources”: true
}
}
チームへのアドバイス
現場でよくある失敗は、「ビルドしたコードと、ソースマップのバージョンが食い違っている」ことだ。CI/CDパイプラインを組む際は、必ずクリーンビルド（`rm -rf dist && tsc`）を通すようにしてくれ。
また、本番環境に `.map` ファイルを上げるかどうかは議論が分かれるところだ。セキュリティ的にソースを見られたくないなら、「Sentry」や「Bugsnag」のようなエラー監視ツールにソースマップをアップロードして、ブラウザ自体には公開しないのが最も賢い選択だ。
—
最後に：エンジニアとして一段上のステージへ
ソースマップを単なる「設定項目」として扱うのではなく、「ブラウザとIDEを繋ぐ架け橋」として捉えてみてほしい。
仕組みを理解していれば、デバッグ中に「なぜかブレークポイントがずれる」という不具合に遭遇したとき、`map`ファイルの中身を覗いて「ああ、パスの解決が間違っているな」と即座に判断できるようになる。
それが、単なるコーダーと、アーキテクトの違いだ。
さあ、tsconfig.jsonを今すぐ見直して、君のチームのデバッグ体験を最高のものにアップグレードしてやろうぜ。応援している。
コメント