typescript-debugging

name	typescript-debugging
description	Diagnose TypeScript compile, module-resolution, declaration, isolated-module, build, and type-check failures. Use when npm or TypeScript gates fail in a Node project.
license	MIT
metadata	{"author":"donmai","version":"1.0.0"}

TypeScript Debugging

Overview

Debugging TypeScript compile and type errors in any Node/TypeScript project. This skill provides systematic diagnosis workflows for the most common failure modes that block npm run build / npm run typecheck.

Triggers

Use this skill when:

• TypeScript type errors block npm run build or npm run typecheck
• The compiler reports module-resolution failures (Cannot find module ...)
• Re-exported types fail under verbatimModuleSyntax / isolatedModules
• Declaration emit (.d.ts) breaks downstream consumers

Debugging Workflow

1. Type Errors

npm run typecheck 2>&1 | head -50

Read the FIRST error. TypeScript errors cascade — fix the root cause first.

Common root causes:

• Missing export type on re-exported types (fix: export type { Foo })
• Incorrect return-type annotations (fix: infer from the implementation)
• Missing @types/* packages for untyped dependencies
• Circular imports (fix: break the cycle with an interface or a barrel file)
• strictNullChecks violations — narrow with a guard before use

2. Module Resolution

npm run build 2>&1 | grep -E "Cannot find module|TS2307|TS2305" | head -20

Common root causes:

• paths in tsconfig.json not mirrored by the bundler/runtime
• ESM/CJS mismatch — "type": "module" requires explicit .js import suffixes
• Workspace dependency not built — build the dependency package first

3. Test Failures

npm test 2>&1 | grep -E "FAIL|Error" | head -30

Common root causes:

• Missing test-environment config (vitest/jest config not picked up)
• Module not found — check moduleNameMapper / resolve.alias
• Async test timeouts — raise the per-test timeout

Notes

• This kit is the FOUNDATION layer; a framework kit (e.g. the Next.js kit) composes on top and adds framework-specific commands and conventions.