一歩先の TypeScript 開発へ！カスタム型定義ファイルの配置と管理のベストプラクティス
2024-07-27
TypeScript でカスタム .d.ts ファイルを配置する場所
プロジェクト直下の types ディレクトリ
これは最も一般的で推奨される方法です。手順は以下の通りです。
- プロジェクト直下に
typesという名前のディレクトリを作成します。 - 作成した
typesディレクトリ内に、カスタム型定義ファイル（例：my-custom-types.d.ts）を配置します。 tsconfig.jsonファイルのcompilerOptions.typeRootsプロパティに、typesディレクトリへのパスを追加します。
例：
{
"compilerOptions": {
"typeRoots": ["./types"]
}
}
この方法の利点は、以下の通りです。
- プロジェクト内で型定義ファイルを管理しやすい。
- IDE などで型定義ファイルを自動的に読み込んでくれる。
@types ディレクトリ
これは、グローバルに利用できる型定義ファイルを配置する場合に使用します。手順は以下の通りです。
- 作成した
@typesディレクトリ内に、パッケージ名に合わせたディレクトリを作成します（例：@types/my-custom-package）。 - パッケージ名に合わせたディレクトリ内に、カスタム型定義ファイル（例：
index.d.ts）を配置します。
@types
└── my-custom-package
└── index.d.ts
- 他のプロジェクトでも同じ型定義ファイルを共有できる。
- npm などでパッケージとして配布できる。
上記以外にも、以下のような方法でカスタム型定義ファイルを配置することもできます。
- 個々の TypeScript ファイルの隣に配置する
- tsconfig.json の
filesプロパティに型定義ファイルのパスを追加する
add(a: number, b: number): number- 2 つの数値を加算する関数
型定義ファイルの作成
まず、@types/my-math という名前のディレクトリを作成し、その中に index.d.ts という名前のファイルを作成します。
// @types/my-math/index.d.ts
declare module "my-math" {
export function add(a: number, b: number): number;
export function multiply(a: number, b: number): number;
}
このファイルは、my-math パッケージが提供する関数の型を宣言しています。
プロジェクトでの利用
次に、プロジェクトでこの型定義ファイルを使用する例を示します。
// main.ts
import * as math from "my-math";
const result1 = math.add(10, 20);
const result2 = math.multiply(5, 3);
console.log(result1); // 30
console.log(result2); // 15
このコードは、my-math パッケージの型定義ファイルを読み込んで、add と multiply 関数をインポートしています。その後、これらの関数を使用して、2 つの数値を加算したり乗算したりしています。
小規模な型定義ファイルの場合は、個々の TypeScript ファイルの隣に配置する方法もあります。
// my-component.ts
// 型定義ファイルをインポート
import "./my-component.d.ts";
class MyComponent {
// ...
}
この方法の利点は、型定義ファイルと実装コードが密接に関連付けられていることです。一方、欠点は、プロジェクト規模が大きくなると管理が難しくなることです。
tsconfig.json の files プロパティに型定義ファイルのパスを追加することで、TypeScript コンパイラにそのファイルを認識させることができます。
{
"compilerOptions": {
"typeRoots": ["./types"],
"files": ["./types/my-custom-type.d.ts"]
}
}
この方法の利点は、types ディレクトリを使用する必要がないことです。一方、欠点は、files プロパティが長くなり、見にくくなる可能性があることです。
どの方法を選択するべきか
- 小規模なプロジェクトの場合は、プロジェクト直下の
typesディレクトリ または 個々の TypeScript ファイルの隣 に配置する方法がおすすめです。 - 中規模から大規模なプロジェクトの場合は、@types ディレクトリ を使用する方が良いでしょう。
- 型定義ファイルが頻繁に変更される場合は、tsconfig.json の
filesプロパティ にパスを追加する方法が便利です。
typescript typescript-typings
