TypeScript 開発をしていて、突然現れる「TS2307: Cannot find module」エラー。このエラーに遭遇すると、プロジェクトが動かなくなり、開発が止まってしまいます。

しかし、このエラーには明確な原因があり、適切な手順で確実に解決できるんです。本記事では、TS2307 エラーの根本原因を 4 つのパターンに分類し、それぞれに対する最短復旧手順をお伝えします。

背景

TypeScript 開発でのモジュール解決の仕組み

TypeScript では、import 文や require 文を使ってモジュールを読み込む際、複雑な解決プロセスが動作しています。TypeScript コンパイラーは以下のステップでモジュールを探索します。

モジュール解決の基本フローを図で確認しましょう。

mermaidCopy codeflowchart TD
  A[import文の解析] --> B{相対パス？}
  B -->|Yes| C[ファイル相対探索]
  B -->|No| D[node_modules探索]
  C --> E{ファイル発見？}
  D --> E
  E -->|Yes| F[型定義チェック]
  E -->|No| G[TS2307エラー]
  F --> H{型定義あり？}
  H -->|Yes| I[解決完了]
  H -->|No| J[型定義エラー]

このフローで問題が発生すると、TS2307 エラーが表示されるのです。

エラーが発生する一般的なシナリオ

TS2307 エラーは主に以下の場面で発生します。

• 新しいパッケージをインストールした直後
• プロジェクトをクローンして yarn install を実行した後
• tsconfig.json の設定を変更した後
• ファイル構成を大幅に変更した後

特にチーム開発では、他の開発者が追加した依存関係が原因でエラーが発生することが多いです。

TS2307 エラーの主要原因

TS2307 エラーは以下の 4 つの主要原因に分類されます。経験上、この順番で確認すると効率的に解決できます。

#	原因カテゴリ	発生頻度	解決難易度
1	パッケージ未インストール	60%	易
2	型定義ファイルの不足	25%	中
3	パス設定の問題	10%	中
4	tsconfig.json 設定不備	5%	難

パッケージ未インストール

最も頻発する原因です。必要なパッケージが node_modules にインストールされていない状態で、そのパッケージを import しようとするとエラーになります。

型定義ファイルの不足

JavaScript ライブラリを使用する際、TypeScript 用の型定義ファイル（@types パッケージ）が不足している場合に発生します。

パス設定の問題

tsconfig.json の baseUrl や paths 設定が不適切な場合、または相対パスの指定ミスが原因です。

tsconfig.json 設定不備

moduleResolution、include、exclude などの設定が適切でない場合に発生する、やや高度な問題です。

原因別解決策

パッケージ関連の問題

yarn add コマンドでの解決手順

パッケージが不足している場合の解決手順です。まず、エラーメッセージから不足しているパッケージ名を特定します。

bashCopy code# エラー例：Cannot find module 'react'の場合
yarn add react

# エラー例：Cannot find module 'lodash'の場合
yarn add lodash

TypeScript プロジェクトでは、通常のパッケージに加えて型定義も必要な場合があります。

bashCopy code# パッケージ本体と型定義を同時にインストール
yarn add lodash
yarn add --dev @types/lodash

キャッシュが原因で正常にインストールされない場合は、強制的に再インストールを実行しましょう。

bashCopy code# node_modulesを削除して再インストール
rm -rf node_modules
yarn install

devDependencies と dependencies の使い分け

パッケージのインストール先を適切に選択することが重要です。以下の基準で判断してください。

dependencies にインストールすべきもの：

• 本番環境でも必要なライブラリ（React、Express 等）
• ランタイムで使用されるパッケージ

bashCopy code# 本番環境で必要なパッケージ
yarn add react react-dom
yarn add express

devDependencies にインストールすべきもの：

• 開発時のみ必要なツール（TypeScript、ESLint 等）
• 型定義ファイル（@types パッケージ）

bashCopy code# 開発時のみ必要なパッケージ
yarn add --dev typescript @types/react
yarn add --dev eslint prettier

型定義ファイルの問題

@types パッケージのインストール方法

JavaScript ライブラリを使用する場合、対応する型定義ファイルのインストールが必要です。

まず、型定義ファイルが存在するか確認しましょう。

bashCopy code# 型定義ファイルの存在確認
yarn info @types/パッケージ名

存在する場合は、以下のコマンドでインストールします。

bashCopy code# 例：axiosライブラリの型定義をインストール
yarn add axios
yarn add --dev @types/axios

DefinitelyTyped に型定義が存在しない場合の対処法も理解しておきましょう。

typescriptCopy code// パッケージに型定義がない場合の一時的対処
declare module 'パッケージ名' {
  const content: any;
  export default content;
}

自作型定義ファイルの作成手順

型定義が存在しないライブラリについては、自分で型定義ファイルを作成できます。

プロジェクトのルートにtypesフォルダを作成し、型定義ファイルを配置します。

bashCopy code# 型定義ファイル用のディレクトリを作成
mkdir types

型定義ファイルを作成します。例として、custom-libraryというパッケージの型定義を作成してみましょう。

typescriptCopy code// types/custom-library.d.ts
declare module 'custom-library' {
  interface CustomConfig {
    apiKey: string;
    timeout?: number;
  }

  export function initialize(config: CustomConfig): void;
  export function getData(id: string): Promise<any>;
}

tsconfig.json で型定義ファイルのパスを指定します。

jsonCopy code{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./types"]
  }
}

パス設定の問題

baseUrl と paths の設定方法

絶対パスで import を行う場合、tsconfig.json でパス設定が必要です。

現在の tsconfig.json の設定を確認しましょう。

jsonCopy code{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

設定後は、以下のようにきれいな import 文が書けるようになります。

typescriptCopy code// 相対パスの場合（設定前）
import Button from '../../../components/ui/Button';
import { formatDate } from '../../../utils/dateUtils';

// 絶対パスの場合（設定後）
import Button from '@components/ui/Button';
import { formatDate } from '@utils/dateUtils';

相対パスと絶対パスの使い分け

プロジェクトの規模に応じて、適切なパス指定方法を選択することが重要です。

相対パスが適している場面：

• 小規模なプロジェクト
• 同一ディレクトリ内での import

typescriptCopy code// 同一ディレクトリ内
import { validateInput } from './validation';

// 親ディレクトリ
import { Button } from '../Button';

絶対パスが適している場面：

• 大規模なプロジェクト
• 深い階層からの共通コンポーネント import

typescriptCopy code// 深い階層からでも簡潔に記述可能
import { API_BASE_URL } from '@/constants/api';
import { useAuth } from '@/hooks/useAuth';

tsconfig.json 設定の問題

moduleResolution の設定

TypeScript のモジュール解決方式を適切に設定する必要があります。

一般的なプロジェクトでは、以下の設定が推奨されます。

jsonCopy code{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true
  }
}

各設定項目の役割を理解しておきましょう。

設定項目	役割	推奨値
moduleResolution	モジュール解決方式	"node"
esModuleInterop	CommonJS と ES モジュールの相互運用	true
allowSyntheticDefaultImports	default import の許可	true
resolveJsonModule	JSON ファイルの import 許可	true

include と exclude の調整

TypeScript コンパイラーが処理するファイルを適切に指定します。

jsonCopy code{
  "include": ["src/**/*", "types/**/*"],
  "exclude": [
    "node_modules",
    "dist",
    "build",
    "**/*.test.ts"
  ]
}

include には必要なファイルを、exclude には処理不要なファイルを指定します。これにより、コンパイル時間の短縮とエラーの防止が可能です。

診断・デバッグ手順

エラー原因の特定方法

TS2307 エラーが発生した際の体系的な診断手順をご紹介します。

以下のチェックリストに沿って、順番に確認していきましょう。

診断フローを図で確認します。

mermaidCopy codeflowchart TD
  A["TS2307エラー発生"] --> B["エラーメッセージ確認"]
  B --> C{"パッケージ名？"}
  C -->|npm package| D["yarn listで確認"]
  C -->|相対パス| E["ファイル存在確認"]
  D --> F{"インストール済み？"}
  F -->|No| G["yarn add実行"]
  F -->|Yes| H["型定義確認"]
  E --> I{"ファイルあり？"}
  I -->|No| J["パス修正"]
  I -->|Yes| K["tsconfig確認"]
  H --> L{"@typesあり？"}
  L -->|No| M["型定義インストール"]
  L -->|Yes| N["設定問題"]

Step 1: エラーメッセージの詳細確認

bashCopy code# TypeScriptコンパイラーで詳細なエラー情報を表示
npx tsc --noEmit --pretty

Step 2: パッケージのインストール状況確認

bashCopy code# 特定パッケージのインストール確認
yarn list --pattern パッケージ名

# 全パッケージの確認
yarn list --depth=0

Step 3: 型定義ファイルの確認

bashCopy code# @typesパッケージの確認
ls node_modules/@types/

# 特定パッケージの型定義確認
yarn list --pattern @types/パッケージ名

VSCode での確認手順

Visual Studio Code を使用している場合の効率的な確認方法です。

TypeScript サーバーの再起動

コマンドパレット（Cmd+Shift+P）から以下を実行します。

arduinoCopy codeTypeScript: Restart TS Server

インポート候補の確認

import 文を入力する際、Ctrl+Space で候補を表示させ、利用可能なモジュールを確認できます。

typescriptCopy code// 入力途中でCtrl+Spaceを押すと候補が表示される
import { } from 'rea // ここでCtrl+Space

問題パネルでの詳細確認

VSCode の問題パネル（View > Problems）で、TS2307 エラーの詳細情報を確認できます。エラーをクリックすると、該当箇所にジャンプします。

設定ファイルの即座編集

Cmd+Shift+P からPreferences: Open Settings (JSON)を選択し、TypeScript 関連の設定を確認・編集できます。

jsonCopy code{
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.suggest.autoImports": true,
  "typescript.updateImportsOnFileMove.enabled": "always"
}

まとめ

TS2307「Cannot find module」エラーは、一見複雑に見えますが、原因を体系的に分類すると確実に解決できます。

本記事でご紹介した 4 つの主要原因と解決策をまとめると以下の通りです。

原因	最初に試すべき解決策	所要時間
パッケージ未インストール	yarn add パッケージ名	1 分
型定義ファイル不足	yarn add --dev @types​/​パッケージ名	2 分
パス設定の問題	tsconfig.json の paths 設定確認	5 分
設定ファイル不備	moduleResolution 設定の見直し	10 分

エラー解決の鉄則

1. エラーメッセージを正確に読み取る
2. 頻度の高い原因から順番に確認する
3. 一つずつ問題を切り分けて対処する
4. 解決後はなぜエラーが発生したかを理解する

これらの手順を覚えておけば、TS2307 エラーに遭遇しても慌てることなく、短時間で開発を再開できるでしょう。TypeScript 開発をより快適に進めていってください。

関連リンク

• TypeScript 公式ドキュメント - Module Resolution
• DefinitelyTyped - 型定義ファイルリポジトリ
• Yarn 公式ドキュメント - パッケージ管理
• TSConfig Reference - TypeScript 設定リファレンス
• VSCode TypeScript 設定ガイド