TypeScript vs JavaScript — the honest comparison

What TypeScript actually is

TypeScript is JavaScript with an extra layer that runs at build time. You write `.ts` or `.tsx` files, the TypeScript compiler (`tsc`, or a faster equivalent like SWC or esbuild) checks the types and strips them out, and the browser or Node runs the resulting plain JavaScript. The types themselves are gone at runtime — TypeScript is a developer-experience tool, not a runtime feature. That's important: it means TypeScript can't protect you from bad data coming in from an API. That job still belongs to a runtime validator like Zod.

What you actually get from adding types

The pitch is 'catch bugs at compile time', but that undersells it. In real codebases the biggest wins are refactoring safety and self-documenting code. When you rename a field, TypeScript tells you every place it broke, including files you'd forgotten existed. When a new engineer joins, they can hover over a function and see exactly what it accepts and returns — no more grepping through implementations.

• Refactor safety — Rename a prop, change a return type, add a required field — the compiler shows you every consumer that broke. This alone typically saves 20–40% of maintenance time on codebases past 30K lines.
• Editor autocomplete that actually works — VS Code's IntelliSense goes from guessing to knowing. Junior engineers ramp faster because the editor tells them what's callable and what shape it returns.
• Fewer 'undefined is not a function' errors in production — Not zero — TypeScript can't validate API responses at runtime — but the whole class of typo bugs and missing-optional-chaining bugs largely disappears.
• Documentation you can't let go stale — The types ARE the docs, and they're enforced. Comments drift; types can't.

What TypeScript costs

It isn't free. There's a real learning curve on the type system (generics, conditional types, discriminated unions), the compiler adds a few seconds to your build, and there's a whole category of situations — third-party libraries with bad types, dynamic runtime data — where you'll fight the compiler. Budget 10–20% slower initial development on a new codebase, offset by 30–50% faster changes once the codebase is 6+ months old.

When to stick with plain JavaScript

• One-off scripts — A 40-line data migration or a build script doesn't need types. The setup cost outweighs the benefit.
• Learning JavaScript — Learn the language first. Adding a type system to something you don't fully understand yet slows you down twice.
• Some legacy embedded contexts — A few older CMS or plugin environments still have friction with TypeScript build steps. Fixable, but sometimes not worth it for a small footprint.
• Prototypes you'll throw away — If the code has a genuinely short life and no successor, plain JS is faster. The trap is that 'prototype' code often becomes production; be honest with yourself.

How to migrate an existing JS codebase

Don't rewrite. Incremental migration is the only realistic path for anything past 20K lines. The sequence we recommend for clients: (1) add a `tsconfig.json` with `allowJs: true` and `strict: false` — nothing breaks; (2) rename one leaf module to `.ts` and fix the errors; (3) work your way up the dependency graph; (4) once the whole codebase is `.ts`, incrementally tighten `strict` settings one flag at a time.

A 100K-line codebase typically takes one engineer 6–10 weeks of part-time work. That's cheap compared to the maintenance savings, and every module converted is immediately safer without waiting for the full migration to finish.