TypeScript Reference ยท Error Codes Worth Knowing
TypeScript error TS2307: Cannot find module
Reference for TypeScript error TS2307: why a module import fails to resolve, how relative paths, file extensions and @types packages matter, and how to fix it.
TS2307 is reported on an import or export ... from whose module specifier TypeScript cannot resolve to a file with types. The text is Cannot find module './x.js' or its corresponding type declarations. Resolution depends on moduleResolution, baseUrl/paths, the package's exports map and the extension you wrote.
For a package without types, the error is usually TS7016 ("Could not find a declaration file for module") because the JavaScript was found but has no types. TS2307 means resolution itself failed.
import { x } from "./missing.js"; // TS2307
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
A declaration for a package you cannot install types for goes in a .d.ts file, because inside a module file declare module "x" is an augmentation of an existing module:
// types/pretend-package.d.ts (no import or export in this file) declare module "pretend-package" { export function hello(): string; }
Syntax
| Cause | Fix |
|---|---|
| Wrong relative path | Fix the path; paths are relative to the importing file. |
Missing extension under nodenext |
Import ./file.js (the output name), even for a .ts source. |
| Package not installed | Install it, then restart the editor server. |
| Package has no types | Install @types/name, or write declare module "name";. |
exports map hides the subpath |
Use a documented entry point, or set moduleResolution appropriately. |
| JSON or asset import | Enable resolveJsonModule; declare modules for assets (*.css). |
paths alias not matched |
Check baseUrl and paths, and make the bundler agree. |
Edge case: a shorthand declare module "name"; makes every import from it any. Prefer a real declaration when you can write one.
Usage notes
nodenextis strict about extensions. Relative imports in ESM must include the extension, and it is the extension of the emitted file (.js), not the.tssource.- Editor vs. build. If the file clearly exists, restart the TypeScript server; the program may have cached the failure.
pathsonly affect the compiler. Node itself does not know your aliases; a bundler or loader must map them too.- Types-only packages. Some packages ship types in a
typesfield, others rely on@types/*. Check thattypeRootsortypesare not excluding it. - Case sensitivity.
./User.jsand./user.jsare different files on Linux even if macOS or Windows let it slide, andforceConsistentCasingInFileNameshelps you catch it. - Dynamic
import()follows the same resolution rules as static imports.
Related
- TS2304
- TS2688
- moduleResolution
- Tutorial: Modules, Declaration files