Cannot find type definition file for 'X' is distinct from the more common "cannot find module" error — this one specifically means TypeScript's compiler was explicitly told (via tsconfig.json's types array, or an automatic scan of @types packages) to include a specific type definition package, and that package isn't actually present in node_modules.
This error means TypeScript's type acquisition process — either automatic (scanning node_modules/@types by default) or explicit (via a types array in tsconfig.json) — expected a type definition package that isn't installed, distinct from a regular import failing to resolve, since this is specifically about the ambient/global type declaration mechanism.
Why This Error Happens
By default, TypeScript automatically includes all @types/* packages found in node_modules as ambient global types, without needing explicit imports. When tsconfig.json's compilerOptions.types array is set explicitly, it overrides this automatic inclusion, listing exactly which @types packages (or custom ambient type files) should be included — if that list references a package name that isn't actually installed, or a stale reference to a package that's since been removed, this error fires.
Reproducing the Error
An explicit types array referencing an uninstalled package:
// tsconfig.json
{
"compilerOptions": {
"types": ["node", "jest", "testing-library__jest-dom"]
}
}
tsc --noEmit
# error TS2688: Cannot find type definition file for 'testing-library__jest-dom'.
# (if @types/testing-library__jest-dom isn't actually installed)
Core Concepts Behind This Error
The types array in tsconfig.json is a narrowing mechanism, not an inclusion mechanism — by default TypeScript includes every @types package found; specifying types explicitly restricts it to only the listed packages, meaning any typo or stale entry in that list produces this error while simultaneously silently excluding every other installed @types package from automatic inclusion, which can cause confusing secondary type errors elsewhere.
Package name to @types package name mapping isn't always obvious for scoped packages — a package like @testing-library/jest-dom maps to a types package literally named @types/testing-library__jest-dom (scope becomes a double-underscore prefix), and getting this transformation wrong in a manually-written types array is a common source of this specific error.
Removing a dependency without removing its corresponding @types package (or a stale types array entry) leaves a dangling reference — this commonly happens after a dependency cleanup pass that removed the runtime package but missed updating tsconfig.json or uninstalling the now-unnecessary @types package.
Monorepo workspace hoisting can cause @types packages to be installed in a different node_modules location than where TypeScript is looking, particularly with strict package manager isolation (like pnpm's default non-hoisted structure) — this produces the same error even though the package genuinely is installed somewhere in the broader repository.
Fixing "Cannot Find Type Definition File"
Fix 1: Install the missing @types package, the most direct fix when it's a genuine omission:
pnpm add -D @types/testing-library__jest-dom
Fix 2: Remove the stale entry from tsconfig.json's types array if the corresponding dependency was already removed:
{
"compilerOptions": {
"types": ["node", "jest"] // removed the stale entry
}
}
Fix 3: Consider removing the explicit types array entirely if you don't have a specific reason to restrict automatic inclusion, letting TypeScript automatically include all installed @types packages:
{
"compilerOptions": {
// "types" array removed — defaults to automatically including all @types packages
}
}
Fix 4: For monorepo/workspace hoisting issues, verify the @types package is actually resolvable from the specific package's node_modules context, adding it as a direct dependency of that specific workspace package if needed:
pnpm add -D @types/node --filter your-package-name
Should You Use an Explicit types Array at All?
Only when you have a specific reason to restrict automatic inclusion — commonly, avoiding global type pollution from a package's ambient types that conflict with another package's types (a real, if relatively rare, scenario). For most projects, omitting the types array and letting TypeScript automatically include every installed @types package is simpler and avoids this entire class of error, since there's no separate list to keep synchronized with your actual dependencies.
Preventing This Error in Production
Avoid an explicit types array in tsconfig.json unless you have a specific, deliberate reason for restricting automatic type inclusion, since it introduces an additional list that needs to stay manually synchronized with your actual installed dependencies. When removing a dependency, check for and remove its corresponding @types package and any explicit tsconfig.json reference in the same change, rather than leaving dangling references for a future error to catch.
If you hit this error, check first whether you have an explicit types array in tsconfig.json — if you don't have a specific reason for restricting it, removing it entirely often resolves this class of error more durably than chasing down each individual missing package.