01 — Why TypeScript: Static Types on Top of JavaScript

"Just JavaScript with extra syntax" was my TypeScript summary, and it put the emphasis on the wrong half. The idea that everything else hangs off: TypeScript is a superset of JavaScript that adds a compile-time type checker, and the types are erased before the code ever runs. [1] The runtime is plain JavaScript; the types are a development-time tool that vanishes.

The framing that finally landed is the timeline. JavaScript is dynamically typed — the engine figures out types as it runs, which means a typo in a property name or a string where I expected a number only surfaces when that line executes, in front of a user. TypeScript moves that check to before the code runs. I write .ts files, a compiler reads them, flags anything that doesn't match the declared shapes, and then emits plain .js with every type annotation stripped out. The browser never sees TypeScript [1][2].

Superset, not a different language

The first thing to internalize: every valid .js file is already a valid .ts file [1]. TypeScript doesn't replace JavaScript syntax — it extends it. I can rename utils.js to utils.ts and the compiler will accept it. This is what makes adoption incremental rather than a rewrite, and it's the reason the language spread the way it did: existing JavaScript isn't a liability, it's a starting point.

The relationship also runs the other way. TypeScript is designed to interoperate with JavaScript seamlessly [2]. I can import a JavaScript library into a TypeScript project, and gradually migrate files one at a time. The compiler can even type-check plain .js files with the right options turned on. The boundary between the two is soft, which is the whole point.

What the types actually buy

The payoff is catching a category of bug at the desk instead of in production. The classic shape of that bug:

function greet(user: { name: string }) {
  return "Hello, " + user.nmae.toUpperCase();
  //                       ^^^^ Property 'nmae' does not exist.
}

In plain JavaScript, user.nmae is undefined, .toUpperCase() throws, and the user sees a blank screen. TypeScript flags the typo with a red underline before I ever run the code [1][2]. Multiply that across a codebase — wrong argument types, missing fields on an API response, a refactor that forgot one call site — and the savings compound. The types also double as always-current documentation: a function signature tells me exactly what it accepts and returns without reading the implementation.

The compiler: tsc

The engine doing the checking is tsc, the TypeScript compiler [3]. It reads .ts files, validates them against the type system, and emits .js. The emit step matters — TypeScript isn't just a linter, it's a transpiler. I tell it which JavaScript version to target (ES5 for old browsers, ESNext for modern), and tsc down-converts syntax as needed. Running tsc from the CLI with no arguments compiles a project according to its config; flags like --noEmit make it type-check only without writing files [3].

For day-to-day work I rarely invoke tsc directly. Bundlers and frameworks wrap it. But knowing it's there matters when a type error appears in a build log — tsc is the thing producing that error.

ts-node and the playground

Two tools smooth out the iteration loop. ts-node runs .ts files directly without a separate compile step — it executes TypeScript in a Node.js environment by compiling on the fly, which is invaluable for scripts and quick experiments [4]. The TypeScript Playground is the browser equivalent: an official online editor where I can type TypeScript, see compilation errors and the emitted JavaScript in real time, and share links to snippets [5]. When I'm unsure how a type feature behaves, the playground answers faster than a full project setup.

Installation and the config file

Getting started is one install and one config file. TypeScript ships as an npm package, and a project's settings live in tsconfig.json — a declarative file at the root that tells tsc how to behave: which files to include, what JavaScript to target, how strict to be [6][7]. That config is what makes a TypeScript build reproducible; it's checked into the repo and shared by every developer and CI run. I'll dig into the specific options in the next notes — the takeaway here is just that the config exists and is the single source of truth for how the compiler treats the project.

How I use this

The way of thinking I keep is the timeline: types live at design and compile time, JavaScript lives at runtime, and the two never meet in the shipped code. When a type error confuses me, I ask whether I'm reasoning about the type system (what tsc sees) or the runtime (what the browser sees) — most of my confusion came from blurring them. And when I adopt TypeScript in an existing JavaScript project, I lean on the superset property: rename files, leave noImplicitAny off at first, and tighten the config over weeks rather than all at once.

References

[1] Microsoft, "TypeScript Handbook: TypeScript in 5 minutes," typescriptlang.org, 2024. [Online]. Available: https://www.typescriptlang.org/docs/handbook/typescript-from-scratch.html

[2] The New Stack, "What Is TypeScript?," 2024. [Online]. Available: https://thenewstack.io/what-is-typescript/

[3] Microsoft, "tsc CLI Options," typescriptlang.org, 2024. [Online]. Available: https://www.typescriptlang.org/docs/handbook/compiler-options.html#using-the-cli

[4] TypeStrong, "ts-node — TypeScript execution and REPL for Node.js," GitHub, 2024. [Online]. Available: https://github.com/TypeStrong/ts-node

[5] Microsoft, "TypeScript Playground," typescriptlang.org, 2024. [Online]. Available: https://www.typescriptlang.org/play

[6] Microsoft, "Install and Configure TypeScript," typescriptlang.org, 2024. [Online]. Available: https://www.typescriptlang.org/download

[7] Microsoft, "What is a tsconfig.json," typescriptlang.org, 2024. [Online]. Available: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#handbook-content