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

問題の概要

TypeScriptプロジェクトでモジュールのインポート時に次のエラーが発生することがあります：

Cannot find module 'module-name' or its corresponding type declarations

このエラーは、Reactプロジェクト（Create React Appで作成）やその他のTypeScript環境で頻繁に発生し、プロジェクトは正常にコンパイル・実行できるにもかかわらず、エディタ上でエラー表示されることが特徴です。

主な原因

このエラーには複数の原因が考えられます：

• 型定義ファイルの不足
• モジュール解決の設定の問題
• キャッシュやIDEの状態の問題
• ファイル命名やインポートパスの誤り

解決方法

1. 型定義のインストール

最も一般的な解決策は、必要な型定義パッケージをインストールすることです：

npm

npm install @types/react @types/react-dom @types/node

yarn

yarn add @types/react @types/react-dom @types/node

利用可能な型定義はDefinitelyTypedリポジトリで管理されています。

2. カスタム型定義ファイルの作成

型定義が存在しないモジュールの場合、独自の型定義ファイル（例：src/types/global.d.ts）を作成します：

declare module 'module-name' {
  // 必要に応じて型定義を追加
  const value: any;
  export default value;
}

3. TypeScriptサーバーの再起動

VS CodeでTypeScriptのキャッシュ問題が原因の場合：

Windows

Ctrl + Shift + P → "TypeScript: Restart TS server"

Mac

⌘ + ⇧ + P → "TypeScript: Restart TS server"

4. tsconfig.jsonの設定確認

tsconfig.jsonで以下の設定を確認・追加します：

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"]
    },
    "moduleResolution": "node"
  },
  "include": ["src", "types"]
}

5. モジュール解決の互換性設定

Node.jsスタイルのモジュール解決を使用する場合：

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext"
  }
}

6. 依存関係の再インストール

キャッシュや依存関係の問題を解消するため：

rm -rf node_modules package-lock.json
npm install

7. ファイル拡張子の明示的指定

インポート時にファイル拡張子を明示的に指定します：

import { Component } from './component.js';

プロジェクトタイプ別の対策

Create React App (CRA) プロジェクト

CRAは内部でTypeScriptを管理しているため、基本的に追加設定は不要ですが、以下の点を確認してください：

1. react-scriptsのバージョンが最新であるか
2. カスタム設定が必要な場合はcracoやreact-app-rewiredを使用

Yarn 2+ / PnP を使用する場合

YarnのPlug'n'Play機能を使用している場合、追加の設定が必要です：

yarn dlx @yarnpkg/sdks vscode
yarn add typescript@latest -D

よくあるシナリオと解決策

画像やアセットのインポートエラー

// types/assets.d.ts
declare module '*.png';
declare module '*.jpg';
declare module '*.jpeg';
declare module '*.gif';
declare module '*.svg';

SCSS/CSSモジュールのインポートエラー

// types/styles.d.ts
declare module '*.scss' {
  const content: { [key: string]: string };
  export default content;
}

トラブルシューティングの手順

1. エラーの特定: どのモジュールでエラーが発生しているか確認
2. 型定義の確認: DefinitelyTypedで型定義の有無を確認
3. 設定の確認: tsconfig.jsonの設定を検証
4. キャッシュのクリア: TypeScriptサーバーやnode_modulesを再起動/再インストール
5. 最小環境でのテスト: 最小限のコードで問題を再現させる

予防策

• プロジェクト初期に適切なTypeScript設定を構成する
• 使用するライブラリの型定義を事前に確認する
• チーム全体で統一した設定を使用する
• 定期的にTypeScriptと型定義を更新する

注意点

型定義をanyで回避することは一時的な解決策としてのみ使用し、本来は適切な型定義を提供することが推奨されます。

このガイドがTypeScriptのモジュール解決問題の解決に役立つことを願っています。問題が解決しない場合は、具体的なエラーメッセージと環境情報を添えてコミュニティに相談してください。