TypeScript Reference ยท Error Codes Worth Knowing
TypeScript error TS2688: cannot find type definition file
TS2688 means a name listed in the types option or a triple-slash types directive has no matching type package. Learn the causes and how to install or remove it.
TS2688 reads Cannot find type definition file for 'node'. It appears when the compiler is told to load a type package by name and cannot find one. There are two ways to give that instruction: the types array in tsconfig.json, and a /// <reference types="..." /> directive. In both cases the name is resolved like a package: the compiler looks for node_modules/@types/<name> or for a package with that name that ships its own types.
A related situation is silent: with no types option at all, the compiler loads every visible @types package automatically. Once you write types, only the listed packages load, which is a common way to break an existing setup.
{ "compilerOptions": { "types": ["node", "jest"] } }
Try it
Fixing this error happens in package.json and tsconfig.json, which a single file cannot reproduce, so the failing configuration is read-only. The example below shows what the right setup buys you: Node's types are present, so built-ins like process and node: imports are known.
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.
Failing setup and its fix, as shell commands:
error TS2688: Cannot find type definition file for 'jest'. npm install --save-dev @types/jest
Syntax
| Cause | Fix |
|---|---|
The package listed in types is not installed |
npm install --save-dev @types/<name> (or the package that ships its own types). |
Misspelt name in types or in a reference directive |
Correct the spelling; the name is the folder under @types. |
Wrong typeRoots |
Point it at the right node_modules/@types folders, or remove it. |
| Monorepo: packages hoisted elsewhere | Add the hoisted node_modules/@types folder to typeRoots, or install in the package that needs it. |
| Name belongs to a global library with no types package | Remove it from types; import the library normally. |
| Package manager did not install devDependencies (production install in CI) | Run the type check before pruning. |
Usage notes
typesis an allow-list."types": []loads no global typings at all, which is useful for browser code that should not see Node globals. Anything you need must be listed.- Imports are separate.
import fs from "node:fs"loads types through module resolution and needs notypesentry as long as the package is installed. - Tests: test frameworks (
jest,mocha,vitest/globals) add global functions such asdescribe; they belong intypesonly for the test tsconfig. - Two tsconfigs. Keep a tests config that extends the base config and adds the test types, so production code cannot use test globals.
- Check what loaded with
tsc --listFilesand look for the@typespaths. - Triple-slash types directives belong in declaration files; in application code prefer the
typesoption.