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

Quick fix flowchart

The exact error string

import { formatDate } from "fancy-date-lib";
// error TS2307: Cannot find module 'fancy-date-lib' or its corresponding type declarations.

import { helper } from "./Utils";
// error TS2307: Cannot find module './Utils' or its corresponding type declarations.

Both lines above throw the identical message, but for entirely different reasons — one is a third-party package with no types, the other is a local file whose name doesn't quite match. TypeScript deliberately collapses several distinct failures into one message, which is exactly why diagnosing TS2307 well means reading the module specifier, not just the error text.

How to diagnose it (read the import path first)

Before touching config, look at what's actually being imported:

• Starts with a package name, no ./ or ../ → a node_modules package. Check install + types (Fix 1 & 2).
• Starts with ./ or ../ → a local file. Check the path, extension, and casing (Fix 3).
• Starts with something like @app/, ~/, or # that isn't a real scoped package you installed → a path alias. Check it's mirrored everywhere (Fix 4).
• The package installs and runs fine with plain Node, but TypeScript alone rejects it → a moduleResolution / exports-map mismatch (Fix 5).
• Importing .json, .svg, .css, or another non-code asset → needs explicit TypeScript support (Fix 6).
• A real build/runtime actually works, only your editor complains → a stale TS language-server cache (Fix 7).
• Fine on your machine, fails only in CI → a lockfile or --save/--save-dev mismatch (see the CI variant right after Fix 1).

Fix 1: the package genuinely isn't installed

The simplest cause is also the most common one during onboarding or after pulling a branch: node_modules is out of sync with package.json.

npm ls fancy-date-lib        # confirm it's actually installed
npm install fancy-date-lib   # install if missing
rm -rf node_modules package-lock.json && npm install   # nuke-and-reinstall if in doubt

In a monorepo, also confirm you're installing at the right workspace level — a package hoisted to the repo root won't help a package nested three levels down if your package manager's workspace linking isn't set up the way you think it is.

A CI-only variant: lockfile drift and npm ci

This same "not installed" cause has a distinctly CI-flavored shape: it works on every developer's machine and fails only in the pipeline. The usual culprit is npm ci, which installs strictly from package-lock.json and does not update it — unlike npm install, which reconciles package.json and the lockfile together.

# locally: package.json has the dependency, so `npm install` just works
npm install fancy-date-lib --save
# ✅ updates both package.json AND package-lock.json

# but if it was accidentally installed as a devDependency...
npm install fancy-date-lib --save-dev
# ❌ fine for local dev/test, but many CI pipelines run
#    `npm ci --omit=dev` for production builds — devDependencies
#    never get installed at all, and the build reports TS2307

Two concrete ways this shows up: someone commits a package.json change but forgets to commit the regenerated package-lock.json, so npm ci in CI installs a stale dependency tree that predates the new import; or a package genuinely needed at runtime gets installed with --save-dev by mistake, so it's simply absent the moment CI runs a production-only install. Fix: install with the correct flag for how the package is actually used, and always commit the lockfile in the same commit as the package.json change that produced it.

Fix 2: installed, but no types anywhere

npm install only guarantees the JavaScript exists. TypeScript separately needs a .d.ts — either bundled with the package itself, or published separately on DefinitelyTyped as @types/<package>. If neither exists, TS2307 is correct: there really is nothing to type-check against.

# check the package's own package.json for a "types" or "typings" field first
cat node_modules/fancy-date-lib/package.json | grep -E '"types"|"typings"'

# then try the community types package
npm install --save-dev @types/fancy-date-lib

If no @types package exists either, write a minimal ambient declaration yourself so TypeScript treats the module as typed (loosely) instead of missing entirely:

// src/types/fancy-date-lib.d.ts
declare module "fancy-date-lib" {
  export function formatDate(input: Date | string, pattern?: string): string;
}

Make sure this file is actually included by your tsconfig.json's include/files array — an ambient declaration TypeScript never loads doesn't help.

Fix 3: a wrong or case-mismatched local path

For relative imports, three sub-causes cover almost every case: a typo in the path, a missing/wrong extension, and — the one that bites hardest — filename casing that differs between your editor's OS and your CI runner's OS.

// file on disk is actually: src/utils.ts (lowercase u)
import { helper } from "./Utils";   // ❌ works on Mac/Windows, fails on Linux CI
import { helper } from "./utils";   // ✅ matches exactly

macOS and Windows filesystems are case-insensitive by default, so a casing mismatch resolves silently on your laptop and only explodes once it hits a case-sensitive Linux CI runner. Turn on this compiler flag so TypeScript catches it locally, before CI does:

{
  "compilerOptions": {
    "forceConsistentCasingInFileNames": true
  }
}

Fix 4: a path alias not mirrored outside tsconfig

This is the fix people miss most often, because it half-works: tsconfig.json's paths is a hint for the type-checker only. It does not rewrite anything at runtime, and most bundlers and test runners know nothing about it unless you tell them separately.

// tsconfig.json — the type-checker's view
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@app/*": ["src/*"] }
  }
}

Editors that use the TypeScript language service (VS Code included) read this and resolve @app/utils just fine — which is exactly why it looks correct while you're writing the code. The same alias then needs to be mirrored, separately, in whichever tool actually runs your code:

// webpack.config.js
resolve: { alias: { "@app": path.resolve(__dirname, "src") } }

// vite.config.ts
resolve: { alias: { "@app": path.resolve(__dirname, "src") } }

// jest.config.js
moduleNameMapper: { "^@app/(.*)$": "<rootDir>/src/$1" }

// running plain ts-node/Node directly — needs a runtime resolver
node -r tsconfig-paths/register dist/index.js

Miss any one of these and that specific tool — not necessarily tsc itself — will report a module-not-found error, sometimes TS2307, sometimes its own bundler-flavored version of the same complaint.

Worked example: a React + Vite project

This exact scenario is one of the most common versions of Fix 4 in practice — a React component imported through an alias, in a Vite project:

// src/App.tsx
import Button from "@/components/Button";
// error TS2307: Cannot find module '@/components/Button' or its corresponding type declarations.

The editor may show no error at all if tsconfig.json already declares the alias — but vite build (or tsc run standalone in CI) fails, because Vite's own dev server and bundler have never been told about it:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  }
}

// vite.config.ts — the piece that's usually missing
import path from "path";
import { defineConfig } from "vite";

export default defineConfig({
  resolve: {
    alias: { "@": path.resolve(__dirname, "src") }
  }
});

Both files need the alias, and they need to agree: tsconfig.json's paths satisfies the type-checker (and your editor), while vite.config.ts's resolve.alias is what actually makes vite build, vite dev, and a standalone tsc run resolve the import for real.

Fix 5: moduleResolution vs a package's exports map

This is the newest and least understood cause. TypeScript's moduleResolution setting controls exactly how strictly it honors a package's package.json exports field:

If a dual ESM/CJS package's exports map forgets to list a "types" condition (or lists it in the wrong order — it must come first), packages that run perfectly under plain Node will still throw TS2307 under the newer resolution modes. There is nothing wrong with your code in this case; it's the package's exports map that's incomplete. Report it upstream, pin an older version, or add a manual override via paths as a stopgap.

Fix 6: non-code assets need explicit TypeScript support

TypeScript only understands .ts/.tsx/.js out of the box. Two common asset imports need one extra step each:

// tsconfig.json — for importing .json files directly
{ "compilerOptions": { "resolveJsonModule": true } }

// src/types/assets.d.ts — for importing .svg/.css/etc. (bundler-processed, not real JS)
declare module "*.svg" {
  const content: string;
  export default content;
}
declare module "*.css";

Without one of these, importing data.json or icon.svg reports the exact same TS2307 as a missing npm package, because from TypeScript's perspective it is the same situation: an import target with no recognized module shape.

Fix 7: restart the TypeScript language server (editor-only staleness)

Not a root cause, but worth ruling out before you go further: your editor's TypeScript language service caches module resolution results, and that cache occasionally goes stale — especially right after installing a new package, adding a path alias, or switching git branches. If a plain terminal build (tsc, or your bundler's build command) actually succeeds while your editor keeps showing TS2307 on the same import, this is almost always the cause.

In VS Code:

• Open the Command Palette: Ctrl+Shift+P (Cmd+Shift+P on macOS)
• Run TypeScript: Restart TS Server

Other editors with a TypeScript language service (WebStorm, Neovim with an LSP client) have an equivalent "restart language server" action. If restarting doesn't help, close and reopen the project entirely — a corrupted .tsbuildinfo incremental-build cache can occasionally survive a language-server restart but not a fresh editor launch.

Worked example: a monorepo package that hasn't been built yet

A workspace layout with packages/shared and packages/app, where app imports from @myorg/shared:

import { formatId } from "@myorg/shared";
// error TS2307: Cannot find module '@myorg/shared' or its corresponding type declarations.

The package exists in the workspace and is correctly listed as a dependency — but its package.json "main"/"types" fields point at a dist/ folder that hasn't been generated yet, because the build order ran app before shared. This is a build-graph problem, not a TypeScript problem: build (or watch) the dependency package first, or configure your monorepo tool's task graph (Turborepo, Nx, or npm/pnpm/yarn workspaces with an explicit build dependency) so shared always builds before anything that imports it.

Common variants of this message

Debugging checklist

• ✓ Read the import specifier first: package name, local path, or alias?
• ✓ Package: npm ls <pkg> to confirm it's actually installed
• ✓ Package installed but still failing? Check for bundled types, then @types/<pkg>, then write your own declare module
• ✓ Only fails in CI? Check for lockfile drift, or the package being installed with --save-dev when a production build needs it
• ✓ Local path: verify the exact filename casing matches on disk (turn on forceConsistentCasingInFileNames)
• ✓ Alias: is it mirrored in webpack/vite/jest/ts-node, not just tsconfig.json?
• ✓ Runs fine under plain Node but not tsc? Check moduleResolution vs the package's exports map
• ✓ Importing .json/.svg/.css? Enable resolveJsonModule or add an ambient declare module
• ✓ Editor-only, and a real build actually succeeds? Restart the TS language server before debugging further
• ✓ Monorepo? Confirm the dependency package has actually been built before the one importing it