Module Not Found Errors in TypeScript

This article addresses the common TypeScript error "Cannot find module '...' or its corresponding type declarations" that occurs when importing dependencies in TypeScript projects. You'll learn various troubleshooting methods and solutions to resolve this issue effectively.

Problem Overview

The error typically occurs when TypeScript's compiler cannot locate or properly interpret module declarations for imported libraries. While your code might compile and run successfully, the error messages in your IDE can be frustrating and hinder development productivity.

Common scenarios where this error appears:

• Missing type definitions for installed packages
• Incorrect TypeScript configuration
• Caching issues in your development environment
• File naming or import path inconsistencies
• Module resolution problems

Solution Approaches

1. Install Type Definitions

For many packages, you need to install corresponding type definitions:

npm install @types/package-name

Example:

npm install @types/react

If type definitions aren't available in the DefinitelyTyped repository, you'll need alternative approaches.

2. Create Custom Type Declarations

Create a declaration file (typically src/types.d.ts or similar) to define modules without types:

declare module "package-name";

For asset imports like images, add declarations for various file types:

declare module '*.png';
declare module '*.jpg';
declare module '*.jpeg';
declare module '*.webp';
declare module '*.svg';

3. Configure TypeScript Properly

Update your tsconfig.json with appropriate settings:

{
  "compilerOptions": {
    "baseUrl": "src/",
    "module": "esnext",
    "moduleResolution": "node",
    "typeRoots": ["./node_modules/@types", "./src/types"]
  },
  "include": ["src", "types"]
}

4. Restart TypeScript Server

Often, simply restarting the TypeScript language server resolves caching issues:

• VSCode: Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
• Command: Select "TypeScript: Restart TS server" or "TypeScript: Reload Project"

5. Clear Caches and Reinstall Dependencies

Remove installed dependencies and lock files, then reinstall:

rm -rf node_modules package-lock.json yarn.lock
npm install

6. Check Import Paths and File Names

Ensure consistent file naming and import paths:

// Correct if file is database.types.ts
import { Database } from "./database.types";

// Sometimes explicit extension is needed
import { Database } from "./database.types.js";

7. Verify Yarn PnP Compatibility (Yarn 2+)

For Yarn 2 with Plug'n'Play, ensure TypeScript compatibility:

# Install supported TypeScript version
yarn add typescript@4.7

# Setup SDKs for your editor
yarn dlx @yarnpkg/sdks vscode

Troubleshooting Steps

Follow this systematic approach to resolve the issue:

Step-by-Step Troubleshooting

1. Restart TypeScript server - Fixes many transient issues
2. Check for type definitions - Install @types/package-name if available
3. Verify tsconfig.json settings - Ensure proper module resolution
4. Clear node_modules and reinstall - Resolves dependency issues
5. Create custom declarations - For packages without types
6. Check file names and import paths - Ensure consistency

Common Pitfalls

• Mixing .ts and .tsx extensions incorrectly
• Incorrect baseUrl or path configuration in tsconfig.json
• Caching issues with TypeScript language server
• Case sensitivity in file names (index.tsx vs Index.tsx)

Advanced Configuration

For complex projects, consider these advanced tsconfig.json settings:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "*": ["src/*", "node_modules/*"]
    },
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

When to Use @ts-ignore

As a temporary measure, you can suppress errors for specific imports:

// @ts-ignore
import Map from 'untyped-package';

However, this should be used sparingly and replaced with proper type declarations when possible.

Conclusion

The "Cannot find module" error in TypeScript typically stems from missing type definitions, configuration issues, or environment problems. By following the systematic approach outlined above—starting with the simplest solutions like restarting the TypeScript server and progressing to more advanced configuration changes—you can resolve these issues and maintain a smooth development experience.

Remember that maintaining proper TypeScript configuration and keeping type definitions up-to-date will prevent most of these errors from occurring in the first place.