エラーメッセージ
TypeScript で Node.js アプリを開発中に TS2688 が表示されると、スタート直後に壁にぶつかったような気分になります。ターミナルや VS Code の「問題」タブには、通常次のメッセージが表示されます：
error TS2688: Cannot find type definition file for 'node'.
The file is in the program because: Entry point of type library 'node' specified in compilerOptions
このエラーはビルドを停止させます。TypeScript がデフォルトでは process、__dirname、Buffer などの Node.js 標準グローバルを認識しないために発生します。
このエラーの原因
TypeScript が Node.js のコマンドを理解するには、専用のマニュアルが必要です。そのマニュアルが存在しないか、パスが壊れていると TS2688 が発生します。主に次の 3 つの原因が考えられます：
- パッケージの未インストール：
@types/nodeパッケージがまだインストールされていません。 - 設定の制限：
tsconfig.jsonのtypes配列に"node"が明示的に記載されているが、node_modulesにファイルが存在しません。 - パスの混乱： カスタムの
typeRoots設定によって、コンパイラが誤ったディレクトリを参照しています。
ステップ 1：Node.js 型定義のインストール
最も素早い修正方法は、不足している型定義をインストールすることです。Node.js はブラウザの標準ライブラリに含まれていないため、TypeScript がその環境を理解するには外部パッケージが必要です。
ターミナルを開き、使用しているパッケージマネージャーに応じたコマンドを実行してください：
npm を使用する場合：
npm install --save-dev @types/node
yarn を使用する場合：
yarn add -D @types/node
pnpm を使用する場合：
pnpm add -D @types/node
必ず -D または --save-dev フラグを付けてください。これらの型定義は開発時にのみ必要であり、本番用のコードを肥大化させるべきではありません。
ステップ 2：tsconfig.json の確認
パッケージは既にインストールされているのにエラーが消えない場合は、tsconfig.json の中を確認してください。compilerOptions セクションが原因であることが多いです。
"types" 配列
types 配列を定義すると、TypeScript は他のパッケージを自動的に検索しなくなります。リストに記載したものだけを読み込みます。node が記載されているのにパッケージのインストールが失敗していると、TS2688 が表示されます。
{
"compilerOptions": {
"types": ["node", "jest"]
}
}
"types" プロパティ自体を削除してみてください。デフォルトでは、TypeScript が node_modules/@types 内のすべてのパッケージを自動的に検出します。
"typeRoots" プロパティ
typeRoots が有効になっていないか確認してください。この設定はデフォルトの検索パスを上書きします。使用する場合は、型定義フォルダへのパスを明示的に含める必要があります：
{
"compilerOptions": {
"typeRoots": ["./node_modules/@types", "./src/custom-types"]
}
}
ステップ 3：環境のリフレッシュ
エディターのキャッシュが同期されていないだけの場合もあります。VS Code は優れたエディターですが、内部の TypeScript サーバーが古いエラーに引っかかってしまうことがあります。
- プロジェクト内の任意の
.tsファイルを開きます。 Ctrl+Shift+P（Windows/Linux）またはCmd+Shift+P（macOS）を押します。- 「TypeScript: Restart TS Server」 を検索して Enter を押します。
それでも解決しない場合は「核オプション」を試してください：node_modules とロックファイル（package-lock.json または pnpm-lock.yaml）を削除し、npm install を再実行します。通常 60 秒もかからず、壊れた依存関係ツリーのほとんどを修正できます。
確認：修正の検証
すべてが正常に動作していることを確認するために、一時的な check.ts ファイルを作成します。次のコードを貼り付けてください：
import os from 'os';
console.log(process.env.NODE_ENV);
console.log(os.platform());
process と os に赤い波線が表示されなければ成功です。process にカーソルを合わせると、NodeJS.Process オブジェクトとして識別するツールチップが表示されるはずです。
プロのヒント
メジャーバージョンを合わせる
実際に使用している Node.js ランタイムのバージョンに合わせて @types/node のバージョンを指定しましょう。Node 20 を使用している場合は、API の微妙な差異を避けるために対応する型定義をインストールしてください：
npm install --save-dev @types/node@20
skipLibCheck を使用する
TS2688 を修正した後に node_modules の内部からエラーが表示されるようになった場合は、設定に skipLibCheck を有効にしてください。これにより .d.ts ファイルの型チェックがスキップされ、ビルドが高速化され、制御できないサードパーティライブラリのエラーを無視できます。
{
"compilerOptions": {
"skipLibCheck": true
}
}