TypeScript Fix, Crash & Optimization Guide

TypeScript is a typed superset of JavaScript that compiles to plain JS via the tsc compiler. It's used across front-end and Node.js codebases. This guide covers install, tsc errors, and faster type-checking/build setups.

Install / First Setup

• Per project (recommended): npm install -D typescript, then run npx tsc --version.
• Globally: npm install -g typescript (avoid if you can — per-project is safer).
• Requires Node.js (see the Node.js guide). Verify with npx tsc --version.

Create a config with npx tsc --init to generate tsconfig.json.

Common Issues & Fixes

tsc: command not found

Cause: TypeScript isn't installed, or npx can't find the local binary. Fix: npm install -D typescript in the project, then use npx tsc. For global use, npm install -g typescript and ensure the global bin is on PATH.

error TS2307: Cannot find module '<x>'

Cause: The module or its type declarations aren't installed, or moduleResolution/paths in tsconfig.json don't match. Fix: npm install <x> (and @types/x for untyped packages). For path aliases, set baseUrl and paths in tsconfig.json. For Node built-ins in ESM, set "moduleResolution": "node16" or "bundler" as appropriate.

Strict-mode type errors (TS2322, TS2739, TS2345)

Cause: strict: true enables null checks, strict property initialization, etc. These flag real type issues, not bugs in the compiler. Fix: Correct the types — add proper annotations, handle undefined, or narrow types. If you must opt out locally, use a type assertion, but prefer fixing the type. To relax globally, set "strict": false (not recommended for new code).

tsconfig.json not being used / wrong files compiled

Cause: You ran tsc without a project, or include/exclude doesn't cover your files. Fix: Run tsc -p tsconfig.json explicitly. Check include (e.g. ["src/**/*"]) and exclude (e.g. node_modules, dist). A stray tsc file.ts compiles a single file and ignores the config.

SyntaxError: Cannot use import statement outside a module

Cause: module/target mismatch — code uses ESM import but output is CommonJS, or Node runs a .ts directly. Fix: Set "module": "ES2020" (or "ESNext") with "target": "ES2020"+ when using ESM, or keep "module": "commonjs" for Node CJS. Never run .ts directly in Node without a loader (ts-node/tsx); compile first with tsc.

Performance & Optimization

• Low-End: Enable incremental: true so tsc writes a .tsbuildinfo and only re-checks changed files. Avoid skipLibCheck: false on huge node_modules type dumps.
• Mid: Use skipLibCheck: true to skip type-checking of declaration files (big speed win, safe for most apps). Set incremental: true and keep tsBuildInfoFile inside node_modules/.cache.
• Workstation: For monorepos, use project references with tsc --build (composite: true per sub-project) so only changed projects recompile. Parallelize CI with --build and cache .tsbuildinfo.

Note: tsc is a type-checker/transpiler, not a bundler. For shipping, pair it with a bundler (esbuild, Vite, webpack); tsc produces JS, the bundler packages it.

Version & Compatibility Notes

• TypeScript 5.x is current; 4.x is older but still common. Major versions add features and sometimes stricter defaults.
• moduleResolution values evolved: "node" (classic), "node16"/"nodenext" (for ESM/CJS with package.json type), and "bundler" (for bundler-based projects). Pick one matching your runtime/bundler.
• target should match the JS features your runtime supports (e.g. ES2020 for Node 14+/modern browsers).
• For exact version and option details, consult official release notes.

FAQ

Q: What's the difference between tsc and a bundler like Vite? A: tsc type-checks and emits JavaScript. A bundler (Vite/webpack/esbuild) combines those JS files and assets into shippable bundles. Most projects run both: tsc for types, the bundler for output.

Q: Should I enable strict mode? A: Yes for new projects — it catches null/undefined and type mistakes early. It surfaces more errors initially but improves long-term safety.

Q: Why is tsc slow on my large project? A: Likely type-checking big node_modules declarations. Enable skipLibCheck: true, incremental: true, and (for monorepos) project references with tsc --build.

Q: How do I run TypeScript directly? A: Use ts-node or tsx for dev (npx tsx file.ts). For production, compile with tsc (or let your bundler handle it) and run the emitted JS.

Q: tsc compiled but my Node app says "cannot find module"? A: Check module/moduleResolution in tsconfig.json match your runtime's module system, and that outDir output is what you're executing. ESM needs "type": "module" in package.json or .mjs files.

Q: How do I exclude test files from the build? A: Add them to exclude in tsconfig.json (e.g. ["node_modules", "dist", "**/*.test.ts"]), or use a separate tsconfig for tests.

Related Guides

• Node.js Fix & Optimization Guide
• JavaScript Fix & Optimization Guide
• Python Fix & Optimization Guide
• Dev RAM Calculator

Accuracy Note

Commands and paths reflect common, real-world setups as of 2026-08. Always verify against your installed version and OS. When in doubt, consult the official TypeScript documentation.