| name | ts-nextjs-debugging |
| description | Diagnose TypeScript and Next.js type, build, module, React Server Component, test, and hydration failures. Use when Next.js or pnpm gates fail or runtime boundaries break. |
| license | MIT |
| metadata | {"author":"donmai","version":"1.0.0"} |
TypeScript and Next.js Debugging
Overview
Debugging TypeScript and Next.js build and runtime errors. This skill provides
systematic diagnosis workflows for the most common failure modes in TS/Next.js
projects.
Triggers
Use this skill when:
- TypeScript type errors block
pnpm build or pnpm typecheck
- Next.js build fails with module resolution or RSC boundary errors
- Test failures indicate type or import mismatches
- Hydration errors appear in the browser console
Debugging Workflow
1. Type Errors
pnpm typecheck 2>&1 | head -50
Read the first error. TypeScript errors often 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 implementation)
- Missing dependencies in
@types/* packages
- Circular imports (fix: break the cycle with an interface or barrel file)
2. Build Failures
pnpm build 2>&1 | tail -80
Common root causes:
- Server/Client Component boundary violations (
'use client' missing)
- Dynamic imports with
ssr: false in Server Components
- Missing environment variables (check
.env.local)
- Invalid image
src domains in next.config
3. Test Failures
pnpm test -- --reporter=verbose 2>&1 | grep -E "FAIL|Error" | head -30
Common root causes:
- Missing test environment setup (check
vitest.config.ts or jest.config.ts)
- Module not found — check
moduleNameMapper or resolve.alias
- Async test timeouts — add
{ timeout: 10000 } to it()
Composition
This is the FRAMEWORK kit; the base default/typescript foundation kit
composes underneath it for any non-framework TypeScript concerns.
