【TypeScript】TS2307の原因と解決方法｜Cannot find module or its type declarationを完全解説

この記事で学べること

• TS2307エラーメッセージの読み方と2つの形式
• npmパッケージが見つからないケースの原因と解決方法
• @types パッケージが必要なケースとインストール方法
• 相対パス・ファイルインポートでのTS2307と正しいパス指定
• パスエイリアス（@/〜）の設定方法とトラブルシューティング
• 画像・CSS・JSONなどの非TSファイルの import 方法
• moduleResolution の設定と各オプションの違い
• monorepo・ワークスペース環境でのTS2307対策
• Next.js・React・Vue.js・Vite などフレームワーク固有の解決方法
• tsconfig.json の設定チェックリスト
• 実務でよくあるTS2307パターン10選

前提知識：この記事はTypeScriptの基本的な構文を理解している方を対象としています。型の基本から学びたい方は【TypeScript】型の書き方 完全入門を先にお読みください。

形式1（最も一般的）：

error TS2307: Cannot find module ‘X’ or its corresponding type declarations.

形式2（型定義なし）：

error TS2307: Cannot find module ‘X’.

src/index.ts:3:22 - error TS2307: Cannot find module 'lodash' or its corresponding type declarations.

3   import _ from 'lodash';
                      ~~~~~~~~

import something from 'モジュール名';

// TypeScript の探索順序:
// 1. 相対パス（./xxx, ../xxx）の場合
//    → 指定パスからファイルを探す（.ts, .tsx, .d.ts, /index.ts ...）
// 2. 非相対パス（lodash, react 等）の場合
//    → node_modules/lodash を探す（.ts, .d.ts, package.json の types ...）
//    → node_modules/@types/lodash を探す
//    → 親ディレクトリの node_modules を再帰的に探す
// 3. tsconfig.json の paths にマッチする場合
//    → paths で指定されたパスを探す
// 4. typeRoots で指定されたディレクトリを探す
//
// すべて見つからない → TS2307 エラー！

ポイント：TS2307 が出たときは、「TypeScript がそのモジュールの場所を見つけられなかった」ということです。モジュールが存在しない場合だけでなく、存在していてもTypeScriptの探索パスから外れている場合にも発生します。

error TS2307: Cannot find module ‘axios’ or its corresponding type declarations.

// axios をインストールしていないのに import している
import axios from 'axios';  // TS2307!

const fetchData = async () => {
  const response = await axios.get('https://api.example.com/data');
  return response.data;
};

# npm の場合
npm install axios

# yarn の場合
yarn add axios

# pnpm の場合
pnpm add axios

ポイント：axios のように TypeScript の型定義が同梱されているパッケージは、パッケージ自体をインストールするだけで TS2307 が解決します。

error TS2307: Cannot find module ‘react’ or its corresponding type declarations.

# node_modules と lockfile を削除して再インストール
rm -rf node_modules package-lock.json
npm install

# yarn の場合
rm -rf node_modules yarn.lock
yarn install

# pnpm の場合
rm -rf node_modules pnpm-lock.yaml
pnpm install

注意：lockfile を削除すると依存関係のバージョンが変わる可能性があります。まずは node_modules だけ削除して npm ci を試すのがおすすめです。

# lockfile はそのまま、node_modules だけ再構築
rm -rf node_modules
npm ci

error TS2307: Cannot find module ‘lodahs’ or its corresponding type declarations.

// よくあるタイポの例
import _ from 'lodahs';        // ✗ lodash のタイポ
import React from 'raect';    // ✗ react のタイポ
import express from 'expresss'; // ✗ express のタイポ

import _ from 'lodash';        // ✓
import React from 'react';    // ✓
import express from 'express'; // ✓

# パッケージがインストールされているか確認
npm ls axios

# 出力例（インストール済み）
my-project@1.0.0
└── axios@1.6.2

error TS2307: Cannot find module ‘tanstack/react-query’ or its corresponding type declarations.

import { useQuery } from 'tanstack/react-query';  // TS2307!

import { useQuery } from '@tanstack/react-query';  // ✓

import deepClone from 'lodash/deepClone';  // TS2307!
import { getAuth } from 'firebase/authentication';  // TS2307!

import cloneDeep from 'lodash/cloneDeep';  // ✓
import { getAuth } from 'firebase/auth';  // ✓

ポイント：サブパスのインポートがうまくいかない場合は、node_modules/パッケージ名/ ディレクトリの構造を直接確認するか、公式ドキュメントで正しいインポートパスを確認しましょう。

error TS2307: Cannot find module ‘express’ or its corresponding type declarations.

// express はインストール済みだが型定義が同梱されていない
import express from 'express';  // TS2307!

const app = express();
app.get('/', (req, res) => {
  res.send('Hello World');
});

# express の型定義をインストール
npm install --save-dev @types/express

# yarn の場合
yarn add -D @types/express

# pnpm の場合
pnpm add -D @types/express

ポイント：@types パッケージは --save-dev（-D）で devDependencies に入れるのが一般的です。型定義は開発時にのみ必要で、本番ビルドには含まれないためです。

# npm で @types パッケージを検索
npm search @types/パッケージ名

# ブラウザで検索
# https://www.npmjs.com/package/@types/パッケージ名
# https://microsoft.github.io/TypeSearch/

// package.json
{
  "dependencies": {
    "react": "^18.2.0"   // React 18.x
  },
  "devDependencies": {
    "@types/react": "^18.2.0"  // @types も 18.x に合わせる
  }
}

error TS2307: Cannot find module ‘obscure-library’ or its corresponding type declarations.

// src/types/obscure-library.d.ts
declare module 'obscure-library';

// これだけで TS2307 は解消する
// ただし、すべての export が any 型になる

// src/types/obscure-library.d.ts
declare module 'obscure-library' {
  export function doSomething(input: string): string;
  export function calculate(a: number, b: number): number;
  export default class ObscureLib {
    constructor(options?: Record<string, unknown>);
    init(): void;
  }
}

注意：typeRoots を指定する場合は ./node_modules/@types も含めてください。指定しないとデフォルトの @types が読み込まれなくなります。

src/
├── components/
│   ├── Button.ts
│   └── Header/
│       └── index.ts
├── utils/
│   └── helpers.ts
└── pages/
    └── Home.ts

error TS2307: Cannot find module ‘./utils/helpers’ or its corresponding type declarations.

// src/pages/Home.ts から utils/helpers.ts をインポート

// NG: ./ は同じディレクトリ（pages/）を指す
import { formatDate } from './utils/helpers';  // TS2307!

// src/pages/Home.ts → src/utils/helpers.ts
import { formatDate } from '../utils/helpers';  // ✓

// src/components/Header/index.ts → src/utils/helpers.ts
import { formatDate } from '../../utils/helpers';  // ✓

// ファイル名: src/components/Button.ts
import { Button } from './Components/button';  // TS2307 (Linux)

import { Button } from './components/Button';  // ✓

// NG: 拡張子なし
import { formatDate } from './utils/helpers';  // TS2307!

// OK: .js 拡張子を付ける（出力ファイルの拡張子）
import { formatDate } from './utils/helpers.js';  // ✓

// ※ ソースは .ts だが import パスには .js を書く

// ファイル: src/components/Button/index.ts

// OK: index.ts は省略できる
import { Button } from './components/Button';  // ✓

// OK: 明示的に指定してもOK
import { Button } from './components/Button/index';  // ✓

注意：moduleResolution: "node16" や "nodenext" では index.ts の省略が効かない場合があります。ESM モードでは明示的に ./components/Button/index.js と指定する必要があります。

// NG: Windows のバックスラッシュ
import { Button } from '.\components\Button';  // TS2307!

// OK: 常にスラッシュを使う
import { Button } from './components/Button';  // ✓

error TS2307: Cannot find module ‘@/components/Button’ or its corresponding type declarations.

// tsconfig.json に paths が設定されていない
import { Button } from '@/components/Button';  // TS2307!

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

ポイント：paths を使うには baseUrl も必ず設定する必要があります。baseUrl はパスの起点となるディレクトリです。

// プロジェクト構造
// project-root/
//   tsconfig.json
//   src/
//     components/
//       Button.ts

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",  // project-root が起点
    "paths": {
      "@/*": ["src/*"]  // @/ → project-root/src/
    }
  }
}

// webpack.config.js
const path = require('path');

module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
};

// vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
});

// tsconfig.json（Next.js プロジェクト）
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "@lib/*": ["./src/lib/*"]
    }
  }
}

error TS2307: Cannot find module ‘./logo.png’ or its corresponding type declarations.

import logo from './logo.png';  // TS2307!
import icon from './icon.svg';  // TS2307!

// src/types/images.d.ts
declare module '*.png' {
  const value: string;
  export default value;
}

declare module '*.jpg' {
  const value: string;
  export default value;
}

declare module '*.jpeg' {
  const value: string;
  export default value;
}

declare module '*.gif' {
  const value: string;
  export default value;
}

declare module '*.svg' {
  const value: string;
  export default value;
}

error TS2307: Cannot find module ‘./styles.module.css’ or its corresponding type declarations.

// src/types/css.d.ts
declare module '*.css' {
  const content: Record<string, string>;
  export default content;
}

declare module '*.scss' {
  const content: Record<string, string>;
  export default content;
}

declare module '*.module.css' {
  const classes: Record<string, string>;
  export default classes;
}

error TS2307: Cannot find module ‘./data.json’.

// tsconfig.json
{
  "compilerOptions": {
    "resolveJsonModule": true,
    "esModuleInterop": true  // 一緒に有効にするのが推奨
  }
}

// data.json が自動的に型付きで import される
import data from './data.json';  // ✓

// data の型は JSON の内容から自動推論される
console.log(data.name);  // 型安全

// tsconfig.json
{
  "compilerOptions": { ... },
  "include": [
    "src/**/*"  // src/ 以下のすべてのファイル（.d.ts 含む）
  ]
}

注意：型宣言ファイルが src/ の外にある場合は、include にそのパスも追加してください。例: "include": ["src/**/*", "types/**/*"]

// フロントエンド（webpack / Vite）向け
{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

// Node.js（ESM）向け
{
  "compilerOptions": {
    "moduleResolution": "node16",
    "module": "node16"
  }
}

// 従来の Node.js（CommonJS）向け
{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

// ESM では拡張子が必須
import { helper } from './utils/helper.js';  // ✓ .js 必須

// ESM では拡張子なしはエラー
import { helper } from './utils/helper';  // TS2307!

// パッケージの package.json
{
  "name": "some-package",
  "exports": {
    ".": "./dist/index.js",
    "./utils": "./dist/utils.js"
    // ./internal は公開されていない
  }
}

// OK: exports に定義されているパス
import { something } from 'some-package';  // ✓
import { util } from 'some-package/utils';  // ✓

// NG: exports に定義されていないパス
import { internal } from 'some-package/internal';  // TS2307!

ポイント：moduleResolution: "node"（従来型）では exports フィールドを無視するため、同じ import が通ります。node16 / nodenext に切り替えたときに TS2307 が増えた場合は、この exports の問題を疑ってください。

monorepo/
├── package.json          # ワークスペース定義
├── packages/
│   ├── shared/           # 共通パッケージ
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── src/index.ts
│   └── web-app/          # Webアプリ
│       ├── package.json
│       ├── tsconfig.json
│       └── src/index.ts

error TS2307: Cannot find module ‘@myorg/shared’ or its corresponding type declarations.

// monorepo/package.json（npm workspaces）
{
  "workspaces": ["packages/*"]
}

// packages/shared/package.json
{
  "name": "@myorg/shared",
  "main": "./src/index.ts",
  "types": "./src/index.ts"
}

// packages/web-app/package.json
{
  "dependencies": {
    "@myorg/shared": "workspace:*"
  }
}

// packages/web-app/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "rootDir": "./src"
  },
  "references": [
    { "path": "../shared" }
  ]
}

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

// .npmrc（pnpm の場合）
# symlink の問題を解決
shamefully-hoist=true

# または特定のパッケージのみ hoist
public-hoist-pattern[]=@types/*
public-hoist-pattern[]=*eslint*

error TS2307: Cannot find module ‘next/image’ or its corresponding type declarations.

# next がインストールされているか確認
npm ls next

# next を再インストール
npm install next@latest

# tsconfig.json に Next.js の型を含める
// tsconfig.json
{
  "compilerOptions": {
    "plugins": [{ "name": "next" }]
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"]
}

注意：Next.js プロジェクトでは next-env.d.ts ファイルが自動生成されます。このファイルが include に含まれていないと、next/image や next/link の型が認識されません。next-env.d.ts は .gitignore に入れないでください。

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",  // React 17+ の新しい JSX 変換
    "moduleResolution": "bundler",
    "lib": ["dom", "dom.iterable", "esnext"]
  }
}

# React + 型定義のインストール
npm install react react-dom
npm install --save-dev @types/react @types/react-dom

error TS2307: Cannot find module ‘./App.vue’ or its corresponding type declarations.

// src/env.d.ts（または src/shims-vue.d.ts）
declare module '*.vue' {
  import type { DefineComponent } from 'vue';
  const component: DefineComponent<{}, {}, any>;
  export default component;
}

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}

// または src/vite-env.d.ts
/// <reference types="vite/client" />

ポイント：Vite は import.meta.env や画像インポートなどの独自機能を持っています。vite/client の型定義を参照することで、これらの型が正しく認識されます。

# @types/node のインストール
npm install --save-dev @types/node

// これで以下のインポートが解決する
import fs from 'fs';        // ✓
import path from 'path';    // ✓
import http from 'http';    // ✓
import { Buffer } from 'buffer';  // ✓

// tsconfig.json（React + Vite プロジェクト向け）
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"]
}

// tsconfig.json（Node.js + Express 向け）
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "node16",
    "moduleResolution": "node16",
    "strict": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

解決方法：rm -rf node_modules && npm install

解決方法：VSCode: Ctrl+Shift+P → "TypeScript: Restart TS Server"

解決方法："include": ["src/**/*", "types/**/*"]

解決方法：npm install --save-dev @types/パッケージ名

解決方法：baseUrl + paths + バンドラー設定の3点セット

解決方法：npm ci を使って依存関係を厳密にインストール

解決方法：node_modules をコンテナ内で再ビルド

解決方法：環境に応じた正しい moduleResolution を設定

解決方法：declare module "*.png" 等の型宣言ファイルを作成

解決方法：workspace 設定 + package.json の dependencies

TS2307 解決フロー

• Step 1: エラーメッセージのモジュール名を確認する
• Step 2: npm パッケージ名か、相対パスか、エイリアスかを判別する
• Step 3（npmパッケージ）: npm ls パッケージ名 でインストール確認 → なければ npm install
• Step 4（@types）: 型定義が同梱されていなければ npm i -D @types/パッケージ名
• Step 5（相対パス）: パスの階層・大文字小文字・拡張子を確認
• Step 6（エイリアス）: tsconfig.json の baseUrl / paths とバンドラー設定を確認
• Step 7（非TSファイル）: .d.ts の型宣言ファイルを作成
• Step 8（moduleResolution）: 環境に合った設定になっているか確認
• Step 9: node_modules を削除して再インストール
• Step 10: IDE の TypeScript サーバーを再起動

TypeScript 関連記事

• 【TypeScript】型の書き方 完全入門 – 基本型から応用型まで体系的に学ぶ
• 【TypeScript】よくあるエラーと解決方法 – 主要エラーコードの一覧と解決策
• 【TypeScript】tsconfig.json 完全ガイド – 全オプションの解説と推奨設定
• 【TypeScript】TS2322の原因と解決方法 – Type is not assignable to type の完全解説
• 【TypeScript】TS2339の原因と解決方法 – Property does not exist on type の完全解説
• 【TypeScript】TS2345の原因と解決方法 – Argument is not assignable の完全解説
• 【TypeScript】TS7006の原因と解決方法 – Parameter implicitly has an any type の完全解説
• 【TypeScript】TS2304の原因と解決方法 – Cannot find name の完全解説
• 【TypeScript】TS2531・TS2532の原因と解決方法 – Object is possibly null/undefined の完全解説