TSer/00 · Prologue · Why TypeScript
CHAPTER 00 · Compile time vs. runtime

Why TypeScript

You already write JavaScript, and it has cost you time: a misspelled property that never reports an error, an undefined that spreads, a NaN on the page. This chapter explains what TypeScript actually solves, and why the rest of the course is worth your time.

§01

It starts with a bill that says $NaN

The most important story in this course. Some version of it happens every day in JavaScript projects.

Day three after the tea shop app went live

You wrote an ordering app for a bubble tea shop. Menu, cart, checkout, all in JavaScript. The tests passed and it went live. One line calculates the two-cup discount: const bill = order.totle * 2. You have probably already spotted it: total is spelled totle.

JavaScript did not spot it. Reading a property that does not exist is not an error in JavaScript. It quietly returns undefined. undefined times 2 is not an error either. It returns NaN. Putting NaN into a string is still not an error. So at 1:47 a.m., a customer buying two cups saw "Total: $NaN", took a screenshot, and sent it to support. You got up at 3 a.m. and read log lines for two hours before you found five letters.

The same code in a .ts file behaves differently. The moment you save the file, the editor underlines it: there is no totle here, did you mean total? It even suggests the fix.

STEP 1
The typo is silent

Reading a missing property is legal JavaScript. You get undefined and no warning, so the place where the bug is born produces no signal at all.

STEP 2
undefined spreads

undefined in an arithmetic expression becomes NaN, and NaN is passed on to whatever comes next. The bad value travels far from where it started.

STEP 3
It surfaces in front of a user

By the time you see the problem, you are far away from the line that caused it. You have to trace backwards from the symptom.

§02

Two timelines: you choose where the error appears

The same typo, two outcomes. Step through it one frame at a time.

Two timelines: one typo, two endings
JS
order.totle ✍️Write the code
Ship it
A user hits it
Debug at 3 a.m.
TS
order.totle ✍️Write the code
Save · red line
Fix it now
Ship it calmly
Two developers, same day, make the same typo in the ordering app for a tea shop: they write totle instead of total. The top lane uses JavaScript, the bottom lane uses TypeScript.
1 / 7

Type checking is like security screening at an airport

Someone will always try to carry something dangerous. The question is whether it is found at the gate or in the air. TypeScript puts the check at the moment you save the file: misspelled properties, wrong arguments, and values that might be undefined are stopped before the code takes off. A few seconds at the gate is cheaper than an incident later.

§03

What a type is: a description of a value's shape

Do not let the phrase "type system" put you off. The idea is simple: agree in advance what each value looks like.

{ drink: string; total: number } means: every order must have a drink that is a string and a total that is a number. That is a type: an agreement, written down before the code runs, about the shape of a value. With the agreement in place, the compiler has something to check against. When you write order.totle, it looks at the agreement, finds no totle, and reports it.

AGREEMENT
A type is a description

It states which fields a value has and what each one holds. Like a delivery note on a box: tapioca pearls, bagged, 5 kg. You know the contents without opening it.

CHECK
The compiler checks it

Every time you use a value, tsc compares it with the description. Does the field exist? Does the type match? If not, it reports the line.

START
TypeScript is a superset of JavaScript

A superset keeps all of JavaScript and adds a layer of types on top. Every line of JavaScript you know still counts. Rename .js to .ts and you have started.

What "superset" means for you

It means TypeScript is not a new language to learn from scratch. Variables, functions, arrays, arrow functions are all the JavaScript you already know. The layer TypeScript adds - annotations, interface, generics - is description, not logic. It describes what your data looks like and what your functions take and return. The remaining eleven chapters teach you how to write and think about that description.

§04

Your first tsc: see the red line yourself

On the left, JavaScript quietly produces NaN. On the right, TypeScript reports the line. This pair of windows is used throughout the course.

order.js · silent failure
1// order.js - no warning at any point
2const order = { drink: "Jasmine Green", total: 22 };
3
4const bill = order.totle * 2; // typo, and nobody says a word
5console.log("Total: $" + bill); // Total: $NaN
JavaScript reasons like this: totle does not exist, so it is undefined. undefined times 2 is NaN. No error anywhere, and the user sees the result.
order.ts · error on save
1// order.ts - same code, only the file extension changed
2const order = { drink: "Jasmine Green", total: 22 };
3
4const bill = order.totle * 2; // red line the moment you save
5console.log("Total: $" + bill);
The exact compiler output: Property 'totle' does not exist on type '{ drink: string; total: number; }'. Did you mean 'total'? Notice that this code has no type annotations at all. TypeScript worked out the shape of order by itself. That ability is called inference, and chapter 01 is about it.

Want to try it right now? The fastest way is the TypeScript Playground. Open typescriptlang.org/play - no account needed. Paste code on the left and the red line appears immediately. Hover over a variable to see its type. The .JS tab on the right shows the compiled output, and you can share a link. Every hands-on task in this course can be done there.

STEP 1
Paste it in

Paste the order.ts code from the right-hand window into the Playground editor. A red underline appears under totle within a second.

STEP 2
Read the error

Hover over the red line and the full message appears. Compiler messages follow a small number of fixed patterns, so they get easy quickly. The tasks below practise reading them.

STEP 3
Look at the output

The .JS tab on the right is the compiled result. You will see that the types are gone. That is type erasure, the subject of §05.

Prefer to run it on your own machine? Three commands, five minutes:

terminal · local setup
1mkdir tea-shop && cd tea-shop
2npm i -D typescript # install the compiler as a dev tool
3npx tsc --init # create tsconfig.json - the subject of chapter 10
4# create order.ts, paste the code above into it, then:
5npx tsc # check and translate: reports totle, produces nothing
6npx tsc --noEmit # check only, no output files - the usual CI command
tsc does two things: it checks, and it translates. Checking means comparing your code against the types and reporting what does not match. Translating means removing the types and writing .js files. You can ask for the two separately: --noEmit means check only, write nothing.
§05

Type erasure: after compiling, no type is left

This is the part of TypeScript that is misunderstood most often, and the part worth understanding early.

Many people assume TypeScript carries the types into the running program and keeps checking there. It does the opposite. After compilation every type is removed (type erasure), the output is ordinary JavaScript, and it behaves exactly like JavaScript you wrote by hand. Use the three buttons below to see it:

Type erasure, step by step
order.ts · source
1type Size = "small" | "medium" | "large";
2interface Order {
3  drink: string;
4  size: Size;
5  total: number;
6}
7 
8const order: Order = { drink: "Jasmine Green", size: "large", total: 22 };
9 
10function priceOf(item: { price: number }): number {
11  return item.price;
12}
Everything in color is written for the compiler: type, interface, and the annotations after each colon. The lines that actually run are the ones below them.

So types do not guard the running program

Type checking applies to the code you write, not to the data that arrives while the program runs. A JSON response with the wrong shape, or strange user input, arrives after the types have been erased, so TypeScript cannot help there. Runtime protection needs real validation code: an if statement you write yourself, or a validation library such as zod. The finale comes back to this and shows how the two layers fit together.

§06

Three ways to run TypeScript code

All three end in the same place: what actually executes is JavaScript with the types removed.

OPTION 1 · CLASSIC
Compile with tsc

npx tsc checks and translates, producing .js files that Node or the browser runs. This is the most direct way to see that TypeScript is only a compile-time tool.

OPTION 2 · EVERYDAY
A bundler transpiles

Build tools such as Vite and esbuild remove the types without checking them, because that is much faster. Checking is left to your editor while you type, and to tsc --noEmit in CI. This is the usual setup for front-end projects.

OPTION 3 · RECENT
Run the .ts file directly

Node 22.18 and later can run a .ts file by stripping the types as it loads, as long as the file uses only erasable syntax (enum, for example, produces runtime code and is not allowed). Deno and Bun have supported this from the start. You skip the build step, but the erasure still happens.

Which one should you pick? Not yet

While you are learning, the Playground is enough: nothing to install, nothing to configure, errors as you type. Chapter 10 covers tsconfig, and that is the point where you set up a real project. For now, remember one thing: all three paths end in JavaScript.

§07

Three common misconceptions

Clear them up now, so they do not get in the way for the next eleven chapters.

Misconception 1: "TypeScript is a different language I have to learn again"

It is not. TypeScript is a superset of JavaScript: every line of JavaScript you have written is still valid, and renaming the file is a real starting point. The only new part is the layer of types, and you can add it gradually. Annotate one function today, describe one object tomorrow. Nothing has to be rewritten.

Misconception 2: "With types, the running program is safe"

Types are erased during compilation, so no check happens while the program runs. TypeScript guarantees that your code is consistent with itself. It cannot guarantee that data coming from outside has the shape you expect. API responses and user input still need validation. The finale shows how to connect the two layers.

Misconception 3: "TypeScript code runs faster"

It does not. The output is ordinary JavaScript, the engine never sees a type, and there is no type-based optimization. What TypeScript speeds up is your work: refactoring is safer, autocompletion is accurate, and you do not spend a night looking for a NaN. The gain is in development, not at runtime.

§08

Course map: twelve chapters, one tea shop

The full route from writing JavaScript to understanding the type system. The dots in the sidebar record your progress.

The whole course uses one example: the tea shop. Chapter 01 gives its menu types, chapter 03 models order state with a discriminated union, chapter 05 writes a generic container for it, chapters 06 and 07 build order variants with utility types, and the finale puts everything together. By the end you will have built the shop's type system from nothing to something you could ship.

§09

Hands-on tasks

Reading is not the same as knowing. Four tasks, so that today is the day TypeScript catches something for you.

§10

Chapter quiz

Seven questions. Get them all right to light up the dot in the sidebar. Every wrong option has its own explanation.

QUESTION 01 / 7

Which statement about the relationship between TypeScript and JavaScript is correct?

QUESTION 02 / 7

When does TypeScript check types?

QUESTION 03 / 7

What does "type erasure" mean?

QUESTION 04 / 7

Which of these actually run a piece of TypeScript code? (Select all that apply.)

QUESTION 05 / 7

In plain JavaScript, what happens when you read order.totle and the real property is called total?

QUESTION 06 / 7

The command line tool for the official TypeScript compiler is called ____ (three letters; you usually run it through npx).

QUESTION 07 / 7

"TypeScript code runs faster than JavaScript." True?

What to take away from this chapter
  • A JavaScript mistake shows up at night in production. A TypeScript mistake shows up when you save the file. You cannot avoid mistakes, but you can choose where they appear.
  • A type describes the shape of a value. It is an agreement written in advance, and the compiler uses it to check every access and every argument.
  • TypeScript is a superset of JavaScript. All of JavaScript stays, and renaming the file is a real starting point. Nothing you already know is wasted.
  • After compilation the types are completely erased and the output is ordinary JavaScript. There is no extra protection and no extra cost at runtime, so data from outside still needs its own validation.
  • tsc checks and translates. There are three ways to run TypeScript (tsc, a bundler, or directly), and all of them end in JavaScript. While you are learning, the Playground is enough.