Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
import { x } from "./missing.js"; // TS2307

Try it

TypeScript A module that does not exist

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.

TypeScript A built-in module needs the node: prefix and types

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.

TypeScript A computed specifier is checked at run time

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:

TypeScript
// 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

  • nodenext is strict about extensions. Relative imports in ESM must include the extension, and it is the extension of the emitted file (.js), not the .ts source.
  • Editor vs. build. If the file clearly exists, restart the TypeScript server; the program may have cached the failure.
  • paths only 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 types field, others rely on @types/*. Check that typeRoots or types are not excluding it.
  • Case sensitivity. ./User.js and ./user.js are different files on Linux even if macOS or Windows let it slide, and forceConsistentCasingInFileNames helps you catch it.
  • Dynamic import() follows the same resolution rules as static imports.