claudekit/reports/agent-research/typescript/build-expert-matrix.csv

CLI tools for Claude Code development workflow

Category,Symptom/Error,Root Cause,Fix 1,Fix 2,Fix 3,Diagnostic Command,Validation Step,Official Link
TSConfig,Cannot find module '@/components',Path mapping only works at compile time,Add bundler alias matching tsconfig paths,Install tsconfig-paths for Node.js,Configure test runner module mapping,npx tsc --traceResolution | grep '@/',npm run build && npm run test,https://www.typescriptlang.org/docs/handbook/module-resolution.html
TSConfig,Module resolution kind 'NodeJs' is deprecated,Old module resolution strategy,Change to moduleResolution: bundler,Update target to ES2022+,Use Node16/NodeNext for Node.js projects,grep moduleResolution tsconfig.json,npx tsc --noEmit,https://devblogs.microsoft.com/typescript/announcing-typescript-4-7/#new-file-extensions
TSConfig,Option 'importsNotUsedAsValues' is deprecated,Replaced by verbatimModuleSyntax,Remove importsNotUsedAsValues,Add verbatimModuleSyntax: true,Update to TypeScript 5.0+ syntax,npx tsc --showConfig | grep -E 'imports|verbatim',npx tsc --noEmit,https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#verbatimmodulesyntax
Performance,TypeScript build is too slow,No incremental compilation,Add incremental: true to tsconfig,Enable tsBuildInfoFile setting,Use skipLibCheck for libraries only,npx tsc --generateTrace trace,time npm run type-check,https://github.com/microsoft/TypeScript/wiki/Performance
Performance,Out of memory during build,Large project type checking,Increase Node.js memory limit,Enable skipLibCheck: true,Split type checking from transpilation,node --max-old-space-size=8192 node_modules/typescript/lib/tsc.js,npm run build,https://github.com/microsoft/TypeScript/wiki/Performance
Build Tool Integration,Webpack ts-loader vs babel-loader confusion,Different transpilation approaches,Use ts-loader for type checking,Use babel-loader + preset-typescript for speed,Separate type checking in parallel,webpack --display-modules | grep -E '\.ts',npm run build && npm run type-check,https://webpack.js.org/guides/typescript/
Build Tool Integration,Vite HMR not working with TypeScript,TypeScript compilation issues,Check vite.config.ts esbuild target,Ensure isolatedModules: true,Update to latest Vite version,npm run dev,Test hot reload in browser,https://vitejs.dev/guide/features.html#typescript
Module Resolution,Circular dependency detected,Import/export cycles,Use import type for type-only imports,Refactor to break circular dependencies,Use dynamic imports where appropriate,npx madge --circular src/,npm run build,https://www.typescriptlang.org/docs/handbook/modules.html#import-type
Module Resolution,Cannot resolve 'node:fs' module,Node.js built-in module resolution,Set moduleResolution: Node16 or NodeNext,Use lib: ['ES2022'] in tsconfig,Install @types/node,npx tsc --traceResolution | grep node:,npm run type-check,https://nodejs.org/api/esm.html#node-imports
Path Mapping,Jest cannot resolve '@/' paths,Test runner doesn't understand tsconfig paths,Configure Jest moduleNameMapper,Install jest-ts-webcompat-resolver,Use ts-jest with pathMapping,npx jest --showConfig | grep moduleNameMapper,npm run test,https://jestjs.io/docs/webpack#handling-static-assets
Path Mapping,ESLint import/no-unresolved with paths,ESLint doesn't resolve TypeScript paths,Configure eslint-plugin-import settings,Use eslint-import-resolver-typescript,Add paths to ESLint import/resolver,npx eslint --print-config src/index.ts | grep import,npm run lint,https://github.com/import-js/eslint-plugin-import/blob/main/resolvers/typescript/README.md
Output,Declaration files not generated,Missing compiler options,Add declaration: true to tsconfig,Set outDir for declaration files,Use composite: true for project references,ls -la dist/*.d.ts,npm run build && ls dist/,https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html
Output,Source maps not working in debugger,Source map configuration issues,Add sourceMap: true to tsconfig,Configure bundler source map settings,Ensure inlineSources: true for debugging,ls -la dist/*.map,Debug in browser/IDE,https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map
Monorepo,Project references not building in order,Missing or incorrect references,Add references array to root tsconfig,Use composite: true in referenced projects,Run tsc --build instead of tsc,npx tsc --build --dry,npx tsc --build,https://www.typescriptlang.org/docs/handbook/project-references.html
Monorepo,Workspace protocol imports not resolved,Package manager workspace setup,Use workspace:* versions in package.json,Configure paths in root tsconfig,Set up proper project references,npm ls --workspaces,npm run build:all,https://docs.npmjs.com/cli/v7/using-npm/workspaces
Watch Mode,Watch mode consuming too much CPU,Inefficient file watching,Configure include/exclude patterns precisely,Use watchOptions in tsconfig,Enable preserveWatchOutput: true,ps aux | grep tsc,Monitor CPU during npm run dev,https://www.typescriptlang.org/docs/handbook/configuring-watch.html
Watch Mode,Changes not detected in watch mode,File system watcher issues,Increase watchOptions.watchFile limit,Use polling: true for network drives,Check exclude patterns aren't too broad,npx tsc --watch --listFilesOnly,Edit file and check rebuild,https://github.com/microsoft/TypeScript/issues/24460
ES Modules,Cannot use import statement outside module,Module system mismatch,Add type: module to package.json,Use .mjs extension or import(),Configure target: ES2022 in tsconfig,node --check dist/index.js,npm run build && node dist/index.js,https://nodejs.org/api/esm.html#modules-ecmascript-modules
ES Modules,require() of ES Module not supported,CommonJS/ESM interop issues,Use dynamic import() instead of require(),Configure esModuleInterop: true,Build separate CJS and ESM outputs,node -e 'console.log(require.resolve(\"./package\"))',npm run build && npm run test:node,https://nodejs.org/api/esm.html#interoperability-with-commonjs
Tree Shaking,Tree shaking not working with TypeScript,Module format or sideEffects issues,Set sideEffects: false in package.json,Use preserveModules in Rollup,Configure module: ESNext in tsconfig,npx webpack-bundle-analyzer dist/,npm run build:analyze,https://webpack.js.org/guides/tree-shaking/
Performance,Type instantiation is excessively deep,Recursive types or complex generics,Add recursion depth limits to types,Use interface extends instead of intersections,Simplify generic constraints,npx tsc --extendedDiagnostics,npm run type-check,https://github.com/microsoft/TypeScript/issues/47663