TypeScript "TS2307: Cannot find module" - Fix in CI

By Daniel Zoghalchali·Latchkey

tsc could not resolve a module or find type declarations for it. Either the package (or its @types) is not installed, the import path is wrong, or your tsconfig resolution settings do not map the specifier.

What this error means

Type-checking fails with error TS2307: Cannot find module '<x>' or its corresponding type declarations. It is deterministic and names the file and import.

src/api/client.ts:2:20 - error TS2307: Cannot find module 'lodash' or its
corresponding type declarations.

2 import debounce from 'lodash'
                       ~~~~~~~~

Common causes

Package or its @types not installed

The runtime package is missing, or it ships no types and the @types/<pkg> package was never installed. tsc needs declarations to resolve the module for type-checking.

Wrong path, alias, or moduleResolution

A path alias (@/) is not declared in paths, or moduleResolution/baseUrl is misconfigured, so tsc cannot map the specifier even when the file exists.

How to fix it

Install the package and its types

npm install lodash
npm install -D @types/lodash   # if the package ships no built-in types

Configure path aliases in tsconfig

Declare baseUrl and paths so aliases resolve, and pick a modern moduleResolution.

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

How to prevent it

• Install @types/* for any dependency without bundled types.
• Keep paths/baseUrl in tsconfig in sync with bundler aliases.
• Run tsc --noEmit in CI so resolution gaps fail before build.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation