This TypeScript error (TS2688) occurs when the compiler cannot locate the .d.ts type definition file for a module in your node_modules directory. The fix typically involves installing the missing @types package or adjusting tsconfig.json settings.
When TypeScript compiles your code, it needs type definitions for all imported modules. These definitions can come from: 1. Built-in type definitions bundled with the module itself 2. Type definitions from the DefinitelyTyped project (installed as @types/package-name) 3. Custom .d.ts declaration files in your project When TypeScript can't find these definitions, it throws error TS2688. This often happens with popular libraries that don't include their own type definitions, or when those definitions aren't properly installed in your node_modules folder. The error is typically a configuration or dependency issue, not a problem with your code.
Look at the error message to find which package is missing type definitions. The error will show something like:
error TS2688: Cannot find type definition file for 'express'In this example, you need type definitions for the 'express' package.
Most popular packages have type definitions available on npm under the @types scope. Install them as a dev dependency:
npm install --save-dev @types/package-nameFor example, for express:
npm install --save-dev @types/expressFor yarn:
yarn add --dev @types/expressFor pnpm:
pnpm add -D @types/expressAfter installation, check that the @types package exists in node_modules:
ls node_modules/@types/expressYou should see a package folder with .d.ts files inside. If you don't, the installation failed. Try deleting node_modules and package-lock.json, then running npm install again.
Many editors cache TypeScript information. After installing types, restart your TypeScript server:
In VS Code:
1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
2. Search for 'TypeScript: Restart TS Server'
3. Press Enter
In other editors:
- Close and reopen the file
- Restart the IDE
- Clear the TypeScript build cache: rm -rf dist/ or your output directory
If the error persists, check your tsconfig.json and ensure proper module resolution:
{
"compilerOptions": {
"moduleResolution": "node",
"skipLibCheck": true,
"esModuleInterop": true,
"resolveJsonModule": true
}
}Key settings:
- moduleResolution: "node" - Tells TypeScript how to find modules (required for npm packages)
- skipLibCheck: true - Skip checking type definitions (speeds up compilation, won't fail on broken types)
- esModuleInterop: true - Enables compatibility with CommonJS modules
### Packages Without Type Definitions
Some packages don't have @types versions available. For these, you have several options:
Option 1: Use declare module (simplest)
Create a .d.ts file in your project:
// types/my-untyped-package.d.ts
declare module 'my-untyped-package' {
export function someFunction(): string;
export interface SomeType {
prop: string;
}
}Option 2: Write a strict any declaration
If typing feels too time-consuming:
declare module 'my-untyped-package';This allows imports but won't provide type safety.
### TypeSync Tool
For large projects, use TypeSync to automatically install missing @types:
npx typesyncThis scans your package.json and installs missing @types packages.
### Module Resolution Strategies
TypeScript 4.7+ supports multiple resolution strategies:
- "node" - Classic Node.js resolution (most compatible)
- "node16"" or "nodenext" - Node 16+ with ESM support (for modern projects)
- "bundler"` - For bundler environments like webpack, esbuild, Vite
If using ES modules exclusively:
{
"compilerOptions": {
"moduleResolution": "bundler",
"module": "esnext"
}
}### Checking if a Package Includes Types
Before installing, check if a package already includes its own types by looking for:
- types or typings field in package.json
- .d.ts files in the package folder
If either exists, don't install @types - the package already provides types.
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript