How to fix Cannot find type definition file for in TypeScript

TypeScriptBEGINNERMEDIUMUpdated Dec 8, 2025· 172 views

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.

Quick fix

Fixes TS2688

error TS2688: Cannot find type definition file for 'express'
  1. Identify the missing package
  2. Install the @types package
  3. Verify the types are installed
  4. Restart TypeScript server in your IDE
typescript — error
error TS2688: Cannot find type definition file for 'express'
Cannot find type definition file for

What this error means

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.

Typical symptoms

  • TypeScript compiler shows error TS2688: 'Cannot find type definition file for X'
  • IDE shows red squiggly lines under an imported module
  • The module works fine at runtime but TypeScript won't compile
  • Error occurs with popular packages like react, express, jquery, etc.
  • Error message references a specific package name you imported
  • Problem started after upgrading TypeScript or dependencies

Common causes

  1. The @types/package-name is not installed (most common for popular libraries)
  2. You have skipLibCheck set to false and a type definition file is missing or corrupted
  3. The package is an older library without bundled type definitions and no @types version exists
  4. node_modules folder is incomplete, corrupted, or out of sync with package-lock.json
  5. TypeScript version is too old to support the module's type definitions
  6. Module resolution in tsconfig.json is incorrectly configured
  7. The module is a local package that doesn't export type definitions

How to fix "Cannot find type definition file for"

1Identify the missing package

Look at the error message to find which package is missing type definitions. The error will show something like:

bash
error TS2688: Cannot find type definition file for 'express'

In this example, you need type definitions for the 'express' package.

2Install the @types package

Most popular packages have type definitions available on npm under the @types scope. Install them as a dev dependency:

bash
npm install --save-dev @types/package-name

For example, for express:

bash
npm install --save-dev @types/express

For yarn:

bash
yarn add --dev @types/express

For pnpm:

bash
pnpm add -D @types/express
3Verify the types are installed

After installation, check that the @types package exists in node_modules:

bash
ls node_modules/@types/express

You 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.

4Restart TypeScript server in your IDE

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

5Update tsconfig.json if needed

If the error persists, check your tsconfig.json and ensure proper module resolution:

json
{
  "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

Advanced notes

### 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:

typescript
// 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:

typescript
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:

bash
npx typesync

This 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:

json
{
  "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.

Frequently asked questions

What does "TS2688" mean?
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.
How do I fix "TS2688"?
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.
What causes "TS2688"?
The @types/package-name is not installed (most common for popular libraries) You have skipLibCheck set to false and a type definition file is missing or corrupted The package is an older library without bundled type definitions and no @types version exists
Is the "TS2688" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading