型ファイルに.d.tsファイルを使うべきか
2025.04.21ことのはじまり
最近見かけたTypeScriptのプロジェクトで、.d.tsファイルが型ファイルとして使用されていたのですが、TypeScriptは通常.tsファイルを使用して型ファイルを書くので、.d.tsファイルを使用することはあまりないと思います。そこで、型ファイルを.d.tsファイルで書くべきなのか、それとも.tsファイルで書くべきなのか調べてみました。
この記事について
【 対象読者 】
- TypeScriptの型ファイルを
.d.tsファイルで書くべきなのか、それとも.tsファイルで書くべきなのかを知りたい方 .d.tsファイルについて知りたい方
【 前提条件 】
- TypeScriptの基本的な知識がある方
結論
型ファイルには.tsファイルを使用してください。
以下本文
【 .d.tsファイルっていつ使うものなの？そもそも何？ 】
サバイバルTypeScriptに.d.tsファイルの説明があったので、それを見てみましょう。
型定義ファイル (.d.ts)
自身のプロジェクトでTypeScriptでコーディングする場合は型を宣言することにより、IDEやエディターの補完機能やコードチェックを行えます。しかし外部のパッケージ(npm)を利用する場合は型定義ファイルが含まれているとは限りません。
型定義ファイルとは
型定義ファイルとはアクセス可能な宣言を記述したファイルです。拡張子は.d.tsです。
型定義ファイルは主にパッケージを配布するために作成されます。TypeScriptはJavaScriptにコンパイルされるときに型情報は無くなってしまいます。そのままJavaScriptパッケージを利用すると型定義の恩恵を得ることができません。しかし型定義ファイルを同梱することにより補完やコードチェックとして利用することができます。
つまり、外部のパッケージ(npm)を使用する際にJavaScriptに型をつけるために使用するのが.d.tsファイルです。
そんなことより結論出ましたね、、、
上記文章より、通常のTypeScriptのプロジェクトでは.tsファイルに普通に型を書けばいい と言外に読み取れます。
とはいえ、.d.tsファイルを通常のTypeScriptプロジェクトで使ってはいけない理由などは書いてないので、使ったら問題が生じるのか、それとも一般的には使わないだけで問題はないのかがまだわかりません。
もう少し深掘りして調べてみましょう。
【 .d.tsファイルを通常の型ファイルとして使用する際のメリット・デメリット 】
メリット
調べた限りメリットはないです。型定義として、普通の.tsファイルより優れている点はなさそうです。
デメリット
デメリットについてですが、これは明確にあります。実は、これが元でこの記事を書こうと決心したのですが、致命的な欠点があります。それは、d.tsファイル内の型は型チェックがすり抜ける場合があるということです。
と、言葉だけで言われても微妙かもしれないので、実際にTypeScriptのプロジェクトを立てて検証してみましょう。
【 d.tsファイルの検証 】
npm init -y
npm install typescript ts-node --save-dev
npx tsc --init
そして、srcフォルダを作成して、src以下に以下のコードを追加してください。
import { Human } from "./index.d";
export function helloWorld(human: Human): string {
return `Hello ${human.name}`;
}
console.log(helloWorld({ name: "John", age: 20 }));
export type Human = {
name: Name;
age: number;
};
このコードは以下で実行できるはずです。
npx ts-node src/index.ts
できましたか？上手くいったらHello John と表示されるはずです。上手くいかなかったらどんまいです。
さて、このコードなのですが、ファイル上でエラーが出ましたか？出ませんでしたよね？Nameとかいう謎の型を突然使用しているのに。
なぜでしょうか？なんでエラーが出ないのでしょうか？
3
2
1..
ダァ！！！！！！！
すいません。乗っ取られてしまったようです。
気を取り直して 、 、 、
正解はtsconfig.json に "skipLibCheck": true /* Skip type checking all .d.ts files. */という設定があるからです。
この設定によって、全ての.d.tsファイルは型チェックがスキップされます。
なぜこのような設定がデフォルトでtrueになるのでしょうか？
結論だけ書くと、
- 型チェックの時間が大幅に短くなる
- そもそも
trueにしないと動かない場合もままある
という話です。詳しくは下記のサイトの説明に譲ります。
というわけで、推奨される設定であるskipLibCheckをtrueにしている限りは型チェックがすり抜ける場合があるのです。
上記のコード例で
console.log(helloWorld({ name: "John", age: 20 })); の部分を
console.log(helloWorld({ name: 111, age: 20 })); に変えて実行しても、怒られることもなくHello 111と返すのを見たら、.d.tsファイルを通常のTypeScriptプロジェクトで使う気はなくなるでしょう。
【 最後のダメ押し 】
念の為、追加の根拠を残しておきます。
下記は、skipLibCheckの設定について調べていたときに見つけた GitHub Issue のリンクです。
このIssueで、Typescriptの開発に関わっているMicrosoftの社員の方が2021年に以下の発言をしています。
Currently, we have a fairly coherent posture that .d.ts files are either outputs or they describe the shape of colocated JS (as in libraries), but they’re not inputs to be hand-authored.
訳すると、
現状では、.d.ts ファイルは出力物であるか、ライブラリなどに同梱される JavaScript の型情報を記述するものであって、手作業で新たに作成する“入力”ファイルではない、という立場をほぼ一貫して採っています。
となります。
ということで、手作業で新たに作成する入力ファイルではないのです。
また、この Issue が Open なままであることが、現在までこの立場が変わっていないことの証左と言えるでしょう。
まとめ
ここまで読んでいただければ分かったかと思いますが、一般的なTypeScriptのプロジェクトで.d.tsを手作業で作成するようなマネはやめましょう。型は普通に.tsファイルに書いてください！！（勿論、.d.tsファイルを使用するべき場所では使用してね！）
参考URL
アノテーション株式会社
アノテーション株式会社は、クラスメソッド社のグループ企業として「オペレーション・エクセレンス」を担える企業を目指してチャレンジを続けています。「らしく働く、らしく生きる」のスローガンを掲げ、様々な背景をもつ多様なメンバーが自由度の高い働き方を通してお客様へサービスを提供し続けてきました。現在当社では一緒に会社を盛り上げていただけるメンバーを募集中です。少しでもご興味あれば、アノテーション株式会社WEBサイトをご覧ください。
