TypeScriptの「型定義だけ吐き出す」という選択：`emitDeclarationOnly`が現場で最強の武器になる理由
現場でバリバリコードを書いている君なら、一度はこんな状況に遭遇したことがあるはずだ。「ライブラリを自作しているんだけど、コンパイル後の`.js`ファイルでプロジェクトが埋め尽くされるのは勘弁してほしい」「ビルドパイプラインはすでに別のツール（esbuildやSWC）が担っているから、TypeScriptには型チェックと型定義の抽出だけに集中してほしい」。
そんな時、`tsconfig.json`の隠れた名脇役である `emitDeclarationOnly` が真価を発揮する。今日は、この設定がなぜ重要なのか、そして現場でどう使いこなすべきかを、泥臭い実務の視点から紐解いていこう。
—
なぜ `emitDeclarationOnly` なのか？
まず、TypeScriptの標準的な挙動を整理しておこう。デフォルトでは、`tsc`を叩くと「型チェック」と「JavaScriptへのトランスパイル」、そしてオプション次第で「型定義ファイル（`.d.ts`）の生成」が行われる。
しかし、現代のフロントエンド開発において、トランスパイルの役割は Babel や esbuild、SWC といった高速なツールに奪われている。TypeScript に JS を吐かせると、出力先ディレクトリが生成物でごちゃごちゃになり、管理コストが跳ね上がる。
ここで `emitDeclarationOnly: true` を設定すると、TypeScript はこう宣言するんだ。
> 「俺はもう JS なんて吐かない。型定義ファイル（`.d.ts`）だけを抽出して、お前のプロジェクトの型安全性を担保してやるよ」
これが、ビルドの責務を分離し、クリーンなプロジェクト構成を保つための「賢い選択」というわけだ。
—
実践：最小構成のtsconfig.json
実務でそのまま使える、堅実な設定例を用意した。これをベースにプロジェクトの要件に合わせて調整してほしい。
{
“compilerOptions”: {
/ 基本設定 /
“target”: “ESNext”,
“module”: “ESNext”,
“moduleResolution”: “node”,
/ ここが本題の核心 /
// TypeScriptにJSを生成させず、型定義ファイルのみを生成する
“declaration”: true,
“emitDeclarationOnly”: true,
/ 出力先の設定 /
“outDir”: “./dist/types”,
/ 型チェックを厳格にする（必須） /
“strict”: true,
“esModuleInterop”: true,
“skipLibCheck”: true,
/ 必要なファイルだけを対象にする /
“include”: [“src//”]
}
}
ブラウザとエンジニア、それぞれの視点
ここで少し深掘りしよう。ブラウザは TypeScript の存在なんて知らない。ブラウザが受け取るのは、あくまで最適化された JavaScript だけだ。
- エンジニア（君）の視点: `emitDeclarationOnly` を使うことで、`tsc` を「型検証のためのCIツール」として切り離せる。トランスパイルは `esbuild` などに任せることで、ビルド速度は劇的に向上する。
- ブラウザの視点: 裏側では、型定義ファイルなんて存在しないかのように振る舞う。ブラウザからすれば、`tsc` が JS を吐こうが吐くまいが、最終的にデプロイされるバンドルファイルさえ正しければいい。
この「責務の分離」こそが、大規模開発で疲弊しないためのアーキテクチャ設計だ。
—
現場で陥りやすい落とし穴
「よし、設定した！」と安心するのはまだ早い。現場でよくある失敗ケースを一つだけ共有しておく。
「`declaration` を書き忘れる問題」
`emitDeclarationOnly` はあくまで「型定義だけを吐く」というフラグに過ぎない。大元の「型定義ファイルを吐く」という指示である `”declaration”: true` が設定されていないと、TypeScript は何も生成してくれない。「あれ？何も出力されないぞ？」と悩んだら、まずここを疑うのが鉄則だ。
まとめ：TypeScriptを「ただの変換ツール」にするな
TypeScript は、単に TS を JS に変換するだけのツールじゃない。プロジェクト全体の品質を守るための「静的解析の守護者」だ。
`emitDeclarationOnly` を使いこなすことは、TypeScript を「トランスパイラとしての役割」から解放し、「型システムという最強のインフラ」へと昇華させる第一歩になる。
もし君のチームで、ビルド後のディレクトリが JS と TS と型定義でカオスになっているなら、今すぐこの設定を検討してほしい。フロントエンドのアーキテクトとして、コードの清潔さを保つことは、君がチームに残せる最高の資産の一つになるはずだ。
また何か詰まったら、いつでも聞きに来てくれ。現場の最前線で戦う君を応援しているぞ。
コメント