TypeScript TS2307: Cannot find module 'X' or its corresponding type declarations

What causes this error

TS2307 fires when TypeScript's module resolution algorithm can't locate the file or package referenced by an import statement. This happens when: the npm package isn't installed, the package exists but has no TypeScript type declarations (no index.d.ts and no @types package), the import path is wrong (typo, missing file extension, wrong relative path), or the tsconfig.json moduleResolution setting doesn't match the project's module system.

How to fix it

1. 01

   step 1

   Check if the package is installed

   The most common cause is a missing npm install. Check node_modules for the package and your package.json for the dependency.

   // Check if installed:
   // ls node_modules/lodash
   // If missing:
   // npm install lodash
   
   // For dev-only packages:
   // npm install -D vitest

   Copy
2. 02

   step 2

   Install @types declarations for untyped packages

   Many JavaScript packages don't include TypeScript declarations. The DefinitelyTyped project provides @types/packagename packages for most popular libraries. Install them as dev dependencies.

   // Package has no built-in types — install from DefinitelyTyped
   // npm install -D @types/express
   // npm install -D @types/node
   // npm install -D @types/react
   
   // Check if @types exists:
   // npm info @types/packagename
   
   // Some packages bundle their own types (no @types needed):
   // zod, drizzle-orm, hono, effect — check for 'types' in package.json

   Copy
3. 03

   step 3

   Fix relative import paths

   For local file imports, verify the path is correct. TypeScript resolves relative imports from the importing file's location. Common mistakes: missing .js extension (required in ESM), wrong directory depth, importing a directory without an index file.

   // Wrong: file is at ./utils/helpers.ts
   import { parse } from './util/helpers'   // typo in directory name
   import { parse } from '../utils/helpers' // wrong depth
   
   // Correct
   import { parse } from './utils/helpers'
   
   // ESM with moduleResolution: 'nodenext' requires .js extension
   import { parse } from './utils/helpers.js'  // .js even for .ts files

   Copy
4. 04

   step 4

   Check tsconfig.json moduleResolution

   The moduleResolution setting controls how TypeScript looks up imports. Mismatches between your module system and resolution strategy cause TS2307. For modern projects: use 'bundler' for Vite/webpack/esbuild, 'nodenext' for Node.js ESM, or 'node' for Node.js CommonJS.

   // tsconfig.json — common configurations
   
   // For Vite, Next.js, or bundled projects:
   {
     "compilerOptions": {
       "moduleResolution": "bundler",
       "module": "esnext"
     }
   }
   
   // For Node.js ESM (package.json has "type": "module"):
   {
     "compilerOptions": {
       "moduleResolution": "nodenext",
       "module": "nodenext"
     }
   }
   
   // For Node.js CommonJS:
   {
     "compilerOptions": {
       "moduleResolution": "node",
       "module": "commonjs"
     }
   }

   Copy
5. 05

   step 5

   Declare modules for untyped packages or non-code imports

   If no @types package exists and you can't type the module fully, create a declaration file (.d.ts) with a module declaration. This is also required for non-code imports like CSS modules, images, and SVGs.

   // src/types/declarations.d.ts
   
   // Minimal declaration for an untyped package
   declare module 'some-untyped-lib' {
     export function doThing(input: string): string
     export default function main(): void
   }
   
   // CSS modules
   declare module '*.module.css' {
     const classes: Record<string, string>
     export default classes
   }
   
   // Image imports (Vite/webpack)
   declare module '*.png' {
     const src: string
     export default src
   }
   
   // SVG as React component (SVGR)
   declare module '*.svg' {
     import type { FC, SVGProps } from 'react'
     const ReactComponent: FC<SVGProps<SVGSVGElement>>
     export default ReactComponent
   }

   Copy

How to verify the fix

• Run tsc --noEmit and confirm TS2307 no longer appears
• Verify the import resolves to the correct file (hover in VS Code to check)
• Ensure .d.ts files are included in tsconfig.json's include or typeRoots