型定義ファイルの配置場所を理解しよう！dependencies、devDependencies、peerDependencies、typeRootsの違いを解説

TypeScript、npm、typescript-typingsにおけるdependenciesとdevDependencies

TypeScriptプロジェクトでpackage.jsonファイルを作成する際、@types/*のような型定義ファイルの配置に悩む場合があります。このドキュメントでは、dependenciesとdevDependenciesそれぞれの役割と、型定義ファイルをどちらに配置すべきかを判断するための指針について解説します。

dependenciesとdevDependenciesの違い

• dependencies: プロジェクトの実行に必須なライブラリを指定します。

型定義ファイルは、TypeScriptコンパイラがコードの型情報を理解するために使用されます。

• dependenciesに配置する場合

  • 型定義ファイルは、プロジェクトの実行時に必要であることを意味します。
  • 型定義ファイルがなければ、プロジェクトは実行できません。
  • 例:
    • @types/node
    • @types/react

判断基準

以下の点を考慮して、型定義ファイルをどちらに配置するか判断します。

• 型定義ファイルは、プロジェクトの実行時に必要ですか？
  • はい: dependenciesに配置

その他の考慮事項

• プロジェクトの規模
• チームメンバーの経験
• 開発環境

package.json

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My TypeScript project",
  "main": "index.js",
  "scripts": {
    "start": "tsc && node index.js",
    "test": "jest"
  },
  "dependencies": {
    "@types/node": "^18.0.0",
    "@types/react": "^18.0.0"
  },
  "devDependencies": {
    "@types/jest": "^28.0.0",
    "@types/eslint": "^8.4.1"
  }
}

index.ts

import React from "react";

function App() {
  return (
    <div>
      <h1>Hello, world!</h1>
    </div>
  );
}

export default App;

解説

• @types/nodeと@types/reactは、プロジェクトの実行時に必須な型定義ファイルです。そのため、dependenciesに配置しています。

実行

npm install
npm start

このコードは、dependenciesとdevDependenciesにそれぞれ型定義ファイルを正しく配置する方法を示しています。

補足

• 上記の例は、一般的なケースに基づいています。プロジェクトによっては、異なる配置が必要になる場合があります。
• 型定義ファイルの配置に迷ったら、npmやtypescriptのドキュメントを参照してください。

型定義ファイルの配置方法

peerDependencies

peerDependenciesは、プロジェクトが動作するために間接的に必要なライブラリを指定します。型定義ファイルの場合、以下の状況でpeerDependenciesを使用できます。

• 型定義ファイルは、プロジェクトの実行時に必須ですが、直接インストールする必要はない場合
• 型定義ファイルは、別のライブラリによって提供される場合

例

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My TypeScript project",
  "main": "index.js",
  "scripts": {
    "start": "tsc && node index.js",
    "test": "jest"
  },
  "peerDependencies": {
    "@types/react": "^18.0.0"
  },
  "dependencies": {
    "@types/node": "^18.0.0"
  },
  "devDependencies": {
    "@types/jest": "^28.0.0",
    "@types/eslint": "^8.4.1"
  }
}

typeRoots

typeRootsは、型定義ファイルを探すディレクトリを指定します。この方法を使用すると、dependenciesやdevDependenciesに型定義ファイルを配置する必要がありません。

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My TypeScript project",
  "main": "index.js",
  "scripts": {
    "start": "tsc && node index.js",
    "test": "jest"
  },
  "typeRoots": [
    "./node_modules/@types",
    "./types"
  ],
  "dependencies": {
    "@types/node": "^18.0.0"
  },
  "devDependencies": {
    "@types/jest": "^28.0.0",
    "@types/eslint": "^8.4.1"
  }
}

ローカルファイル

型定義ファイルをローカルファイルとして保存することもできます。この方法は、プライベートな型定義ファイルを使用する場合に便利です。

// types/index.d.ts

declare module "my-module" {
  export interface MyInterface {
    name: string;
    age: number;
  }
}

import { MyInterface } from "my-module";

function foo(myInterface: MyInterface): void {
  // ...
}

dependenciesとdevDependencies以外にも、型定義ファイルを配置する方法はいくつかあります。プロジェクトの状況に合わせて、適切な方法を選択してください。