TypeScriptモジュール解決エラーの解決方法

TypeScriptプロジェクトで外部パッケージをインポートする際に「Cannot find module」エラーが発生する場合、その原因と解決方法について解説します。特にts-transformer-keysパッケージのインポートエラーを例に取り上げます。

問題の概要

以下のようなエラーメッセージが表示される場合：

Cannot find module 'ts-transformer-keys'. Did you mean to set the 'moduleResolution' option to 'node', or to add aliases to 'paths' option?ts(2792)

これはTypeScriptがnode_modulesディレクトリからモジュールを正しく解決できないことを示しています。

根本原因

TypeScriptのデフォルトのモジュール解決方式（旧来の「classic」方式）は、node_modulesディレクトリを自動的に検索しません。そのため、外部パッケージをインポートする際にモジュールが見つからないエラーが発生します。

モジュール解決とは

モジュール解決は、インポート文に指定されたモジュールのパスを実際のファイルシステム上の位置に対応付けるプロセスです。

解決方法

方法1: moduleResolutionの設定変更

最も一般的な解決策は、tsconfig.jsonファイルのmoduleResolutionオプションを適切な値に設定することです。

{
  "compilerOptions": {
    // 他のオプション...
    "moduleResolution": "node16"
  }
}

推奨設定

現在のTypeScriptバージョンでは、"moduleResolution": "node16"または"nodeNext"が推奨されます。古いバージョンでは"node"を使用します。

方法2: JavaScriptプロジェクトの場合

JavaScriptプロジェクトでTypeScriptコンパイラを使用している場合は、jsconfig.jsonファイルを作成し、同様の設定を行う必要があります。

{
  "compilerOptions": {
    "moduleResolution": "node16"
  }
}

VSCodeでの設定ファイルの確認方法

VSCodeを使用している場合、ステータスバーに{} JavaScriptまたは{} TypeScriptと表示されます。{}アイコンにマウスをホバーすると、現在使用されている設定ファイルの情報が表示されます。

方法3: IDEの再起動

設定を変更した後もエラーが解消されない場合は、開発環境（VSCodeなど）を再起動してみてください。これはキャッシュされた型情報が更新されない場合に有効です。

補足情報

ts-transformer-keysの正しい設定

ts-transformer-keysを使用する場合、tsconfig.jsonに次の設定も必要です：

{
  "compilerOptions": {
    "plugins": [
      { "transform": "ts-transformer-keys/transformer" }
    ]
  }
}

モジュール解決戦略の比較

解決方式	説明	適用ケース
classic	旧来の方式、node_modulesを検索しない	レガシーなプロジェクト
node	Node.jsの解決アルゴリズムを模倣	Node.jsアプリケーション
node16/nodenext	ES ModulesとCommonJSの混合対応	最新のNode.jsプロジェクト

トラブルシューティング

設定変更後も問題が解決しない場合は、以下を確認してください：

1. パッケージが正しくインストールされているか：node_modulesディレクトリを確認
2. TypeScriptバージョンが適切か：古いバージョンでは新しい解決方式をサポートしていない場合があります
3. 設定ファイルの場所：プロジェクトルートに正しく配置されているか

まとめ

TypeScriptで「Cannot find module」エラーが発生した場合、まずmoduleResolutionオプションの設定を見直してください。現代的なTypeScriptプロジェクトでは"node16"または"nodenext"の設定が推奨されます。設定変更後は開発環境の再起動も忘れずに行いましょう。