できない.dev

TypeScript「Cannot find module ... or its corresponding type declarations」の原因と直し方

Cannot find module(TS2307)は、本体か @types/* を入れるか moduleResolution を直せば消える。
tsc から本体か型定義が見えないときに出るので、どこで切れているかを順に確かめる。

公開: 更新:

症状できない · exit 2
npx tsc
src/main.ts(2,21): error TS2307: Cannot find module 'left-pad' or its corresponding type declarations.
解決後できた · exit 0
npx tsc

2026-10-22 に node:20(TypeScript 5.9.3 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

Cannot find module 'foo' or its corresponding type declarations. は、実体のモジュールか型定義のどちらか(または両方)が tsc から見えない ことを意味する。
tsc は node_modules/<pkg> と node_modules/@types/<pkg>、および tsconfig の paths を探索する。
どこで切れているかを順に確認する。

実行例

node:20 環境で上記の手順を動かすと、left-pad に対して Cannot find module 'left-pad' or its corresponding type declarations.(TS2307、終了コード 2)が出た。
declare module による暫定宣言を追加すると、終了コード 0 になり型解決が通った。

Version 5.9.3
$ npx tsc
src/main.ts(2,21): error TS2307: Cannot find module 'left-pad' or its corresponding type declarations.
$ echo $?
2
$ npx tsc
$ echo $?
0

— 2026-10-22 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-22 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • TypeScript 5.9.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 本体と型を入れる

npm install foo
npm install -D @types/foo

ライブラリが型同梱(d.ts を含む)なら 2 行目は要らない。
@types/foo の有無は npm のパッケージページか npm view @types/foo で確認する。

2. 自前の型宣言で塞ぐ

src/types/foo.d.ts:

declare module "foo";

DefinitelyTyped にも無い小さなライブラリには、この宣言で暫定的に対処する。
tsconfig.json の include か typeRoots でこの .d.ts が拾われていることを確認する。

3. moduleResolution を現代仕様に

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler"
  }
}

選択基準は tsconfig の moduleResolution(新しいタブで開く) に書かれている。
Node 単体実行なら "nodenext"、Vite / webpack / esbuild など bundler 経由なら "bundler" を選ぶ。

4. 解決経路の検証

npx tsc --traceResolution > resolve.log

tsc が候補ファイルを順に試すログが出る。
期待した node_modules を見ていなければ paths や baseUrl の誤りを疑う。

よくある原因

  1. 本体をインストールしていない。
    ランタイム用パッケージ自体が node_modules に無い。
  2. @types/* をインストールしていない。
    ライブラリが型を同梱せず、DefinitelyTyped 経由でしか型が提供されていない。
  3. moduleResolution が合っていない。
    TypeScript 5.x で module が es2015 などだと既定が "classic" になり、node_modules を探さない(TS2792)。
    "classic" は 6.0 で非推奨(TS5107)になり、7.0 で削除された(TS5108)。
    "node16" / "bundler" の解決規則を満たしていない場合もある。
  4. paths の解決が崩れている。
    tsconfig.json の paths で書いたエイリアス先のファイルが移動・改名された。