型定義ファイル (.d.ts)
別名: .d.ts / declaration file / 宣言ファイル / @types
拡張子 .d.ts の、型の情報だけを書いた TypeScript のファイル。
実装は持たず、JavaScript のライブラリやグローバル変数がどんな型を持つかをコンパイラに伝える。
npm では @types/ パッケージとしても配布される。
公開:
定義
型定義ファイル(.d.ts)は、型の情報だけを書いた TypeScript のファイルである。
関数やクラスの実装は持たず、「このモジュールはこういう名前と型のものを公開している」という形だけをコンパイラに伝える。
詳細
型定義の入手先は 3 通りある。
パッケージ自身が .d.ts を同梱している場合、DefinitelyTyped で作られた @types/パッケージ名 を npm install -D で追加する場合、どちらも無いときに declare module "pkg"; などを書いた .d.ts を自作する場合である。
自作の .d.ts は tsconfig.json の include の範囲に入っていないと読まれない。declaration オプションを有効にすると、tsc は自分のコードからも .d.ts を書き出す。
よくある誤解
node_modules/@typesが常に全部読まれるわけではない。
TypeScript 5.9 までは既定でそうだったが、6.0 からtypesの既定値が[]になった。importせずに使う@types/nodeのようなグローバルな型は、"types": ["node"]のように列挙しないと見つからない。.d.tsを足しても、実行時の動作は直らない。
型定義はコンパイル時の検査にだけ使われ、出力される JavaScript には含まれない。
関連
型定義が見つからない場合は、TypeScript で「Cannot find module ... or its corresponding type declarations」が出る で切り分けられる。
JSX で型が付かない場合は、TypeScript で TSX の JSX 要素が implicit any になる(TS7026) で切り分けられる。