typedoc "error TS2307: Cannot find module" in docs build

TL;DR

Give TypeDoc the same module resolution your build uses: point it at the right tsconfig with correct paths and moduleResolution. TS2307 in TypeDoc almost always means it loaded a different tsconfig than your bundler.

Error

error TS2307: Cannot find module '@/components/Button' or its corresponding type declarations.

Steps

1. Find which tsconfig TypeDoc is using: pass --tsconfig explicitly pointing at the tsconfig your app builds with. Expected: you know the exact config file in play.
2. Check that tsconfig's compilerOptions.paths covers the failing import and that moduleResolution is set (node16/nodenext or bundler, matching your toolchain). Expected: the paths mapping includes the alias.
3. Verify baseUrl is set if your paths are relative to it; a missing baseUrl silently breaks path aliases. Expected: baseUrl plus paths resolve the import.
4. Re-run npx typedoc --tsconfig tsconfig.json. Expected: TS2307 is gone.

When to use

• TypeDoc reports TS2307 for aliased or workspace imports
• The app builds fine but the docs build does not
• A monorepo package is documented standalone

When not to use

• The module genuinely does not exist (install it or fix the import)
• TypeDoc warns about entry points rather than reporting TS errors
• You want to document despite broken imports (use skipErrorChecking, but fix the config instead when you can)

Tool compatibility

TypeDoc 0.24 through 0.28 with TypeScript 5.x. Path alias behavior follows the TS version.

Variant phrasings

TS2307 only for workspace sibling packages

The sibling package needs built type declarations, or TypeDoc needs the monorepo root tsconfig with project references resolved.

cannot find module for a types-only package

Ensure the @types package is installed in the environment running TypeDoc, not just in the app workspace.

Why it happens

Editors and bundlers resolve aliases through your project's tsconfig, but TypeDoc defaults to the nearest tsconfig.json, which may be a docs-specific one without the aliases. The mismatch surfaces as TS2307 even though the code is fine.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst5ldw6-1mCZ6bxQwKWQmGQ