Cannot find module '<package>' or its corresponding type declarations

What causes this error

The TypeScript compiler refuses to type-check a file when it cannot locate either the runtime module or a .d.ts declaration for the imported package. In a Vite project this surfaces in four distinct shapes, and conflating them is the single biggest reason fixes fail to stick.

The first shape is missing type declarations for a package that ships untyped JavaScript. The runtime works — pnpm dev boots, the import executes — but tsc --noEmit fails because no @types/<pkg> package is installed and the upstream maintainer has not bundled *.d.ts files. The second shape is a path alias declared in tsconfig.json under compilerOptions.paths that has not been mirrored in vite.config.ts under resolve.alias (or vice versa). TypeScript and Vite each maintain their own resolver — declaring @/* in one but not the other means the type checker resolves the import while Vite cannot, or the inverse. The third shape is a monorepo workspace package whose dist/ directory has not been built — pnpm -r build produces the artifact the consumer’s package.json exports field points at, and without it the consumer sees the shell of a package with no resolvable entry. The fourth shape is an ESM-only package imported by a tooling layer that still expects CommonJS — Vite handles ESM natively but a lint or codegen step running outside Vite can still trip on it.

How to fix it manually

Run pnpm exec tsc --noEmit and read the full error — TypeScript prints both the import path it tried and the resolution roots it searched. If the package ships its own types, run pnpm add <pkg> again and check node_modules/<pkg>/package.json for a types field. If not, run pnpm add -D @types/<pkg>. For alias misconfig, open tsconfig.json and vite.config.ts side by side and confirm the paths map and resolve.alias entries match. For monorepo issues, run pnpm -r --filter <consumer>... build to rebuild every transitive dependency in the workspace graph.

Copy this prompt into your AI coding agent

# Goal
Resolve this TypeScript "Cannot find module" error using the smallest safe change.
The runtime may already work; the failure is at type-check time. Diagnose which of
the four shapes applies before patching.

# Context

Error output:

<paste the full tsc --noEmit output here, including the path it tried and the resolution roots>

The package at issue: <package name>
The importing file: <relative path>

# In-scope

- tsconfig.json compilerOptions.paths
- vite.config.ts resolve.alias
- package.json dependencies / devDependencies
- The single failing import statement

# Out-of-scope

- Renaming the package or changing the import name
- Restructuring the monorepo workspace layout
- Switching module systems (ESM <-> CommonJS) globally
- Adding new build steps to the pipeline

# Verification

Run `pnpm exec tsc --noEmit` and confirm exit code 0.
Run `pnpm build` and confirm the production bundle compiles.
Run `pnpm dev` and confirm the importing file loads without console errors.

# Output format

1. One sentence: which of the four shapes this is (missing types / alias mismatch / monorepo / ESM-CJS).
2. The diff (only changed files; full file contents not required).
3. The verification command output, truncated to the last 10 lines.

Why this prompt works

The four-shapes framing forces the agent to commit to a hypothesis before patching, which suppresses Claude Code’s tendency to install @types/<pkg> when the real problem is an alias. Naming tsconfig.json and vite.config.ts in In-scope keeps the fix inside the resolver pair instead of triggering a refactor of the importing module. The Verification block names tsc --noEmit first because it answers the question in three seconds rather than thirty — running pnpm build first wastes a build cycle on a problem the type-checker already fingerprints.

Variants by symptom

Related errors and tools

• Failed to resolve import — sibling Vite resolver error
• Vite build error — when production differs from dev
• AI Bug Fix Prompt Generator — parameterised version
• Claude Code Bug Fix Prompt — full template walkthrough
• Vite CLAUDE.md template — lock alias decisions in project context