How TypeScript works

One command, two jobs

In the last lesson you saw TypeScript mark a mistake while you typed, and you saw that the browser runs plain JavaScript. This lesson follows one file through that process, step by step. Here is the price bug again, saved in a file called cart.ts:

1const teaPrice: number = 3;2const cakePrice: number = "4";3console.log(teaPrice + cakePrice);

Line 1 says teaPrice is a number and gives it 3. Line 2 says cakePrice is a number too, but gives it the text "4". Line 3 adds the two and prints the result. The error on line 2 is on purpose: it's the bug this lesson follows.

The program that turns TypeScript into JavaScript is the TypeScript compiler. Its command is tsc (the next lesson installs it). A compiler is a program that reads code in one form and writes it in another. You give it the file name in a terminal, the window where you type commands:

tsc --target es2022 cart.ts

tsc is the command, and cart.ts is the file to compile. --target es2022 asks for modern JavaScript, so the output looks like the code you wrote; the emitting section shows what happens without it. Here is what tsc prints:

cart.ts:2:7 - error TS2322: Type 'string' is not assignable to type 'number'.

2 const cakePrice: number = "4";
        ~~~~~~~~~

Found 1 error in cart.ts:2

Read the terminal output one line at a time:

• Line 1 names the file, line, and column (cart.ts:2:7 means line 2, character 7), then the error number TS2322 and the message: text is going where a number has to go.
• Lines 3 and 4 copy line 2 of your code and draw ~~~~~~~~~ under the name the error is about.
• The last line counts the errors and says where they are.

That's the first job: checking. But tsc also did a second job, quietly. A new file appeared next to cart.ts:

const teaPrice = 3;
const cakePrice = "4";
console.log(teaPrice + cakePrice);

This is the second job, called emitting: writing JavaScript. Lines 1 and 2 have lost their : number. Everything else is your code, exactly as you wrote it, error and all. Press Edit & run and it prints 34, the same bug as before.

Checking reads your code without running it

Checking is called a static check. "Static" means "without running": TypeScript only reads the text of your code. That's why it can check code that never runs at all:

1function couponLabel(percent: number) {2  return percent.toUpperCase();3}4 5console.log("Coupons are off today");

Line 1 declares a couponLabel function that takes a percent, a number. Line 2 calls toUpperCase on it, but numbers have no such method; it belongs to text. Line 5 prints a message, and nothing ever calls couponLabel.

TypeScript marks line 2 on purpose: Property 'toUpperCase' does not exist on type 'number'. In plain words: "numbers don't have toUpperCase". A property is a named thing a value has, like a method. Plain JavaScript can't notice this mistake until someone calls the function, maybe weeks later. When the code runs, it prints Coupons are off today, because line 2 never runs.

To check, TypeScript has to know the type of every value. Most of them it works out by reading, which is called inference. Here it works out a type through a whole map call, without running it:

1const cart = [2  { name: "Tea", price: 3 },3  { name: "Cake", price: 4 },4];5const prices = cart.map((item) => item.price);6//    ^?7console.log(prices.join(", "));

Lines 1 to 4 make a cart list with tea and cake. Line 5 uses map to make a new list of just the prices. The // ^? comment on line 6 asks TypeScript what type prices has, and the page shows its answer: const prices: number[]. number[] means "a list of numbers". TypeScript knew each item.price is a number, so the list map gives back must hold numbers. Line 7 prints 3, 4.

Emitting writes plain JavaScript

The second job takes the same file and writes JavaScript. It mostly removes things. Here is a typed function with a type alias, a name for a type made with the type keyword:

1type CartItem = { name: string; price: number };2 3function lineTotal(item: CartItem, quantity: number): number {4  return item.price * quantity;5}6 7const tea: CartItem = { name: "Tea", price: 3 };8console.log(lineTotal(tea, 2));

Line 1 names a type, CartItem: an object with a name that is text and a price that is a number. Line 3 declares lineTotal, which takes a CartItem and a quantity, and says it gives back a number (the : number after the brackets). Line 4 multiplies. Line 7 makes a tea item, and line 8 prints 6. There are no errors. Here is the cart.js that tsc --target es2022 writes for it:

function lineTotal(item, quantity) {
    return item.price * quantity;
}
const tea = { name: "Tea", price: 3 };
console.log(lineTotal(tea, 2));

• The type CartItem line is gone. A type alias is only for TypeScript, so nothing of it is left.
• Line 1 has lost : CartItem, : number, and the : number after the brackets.
• Line 4 has lost : CartItem. The object itself is copied as it is.
• The empty lines are gone, and the body is indented with four spaces. That's only how tsc lays out its output.

It still prints 6. Removing types like this is called type erasure.

The table below shows what happens to each kind of thing in a .ts file. Read each row: this part of your code, what emitting does to it, and what's left.

Emitting can do one more thing: rewrite new JavaScript as older JavaScript, for old browsers. This is called downleveling (the Transpilers & polyfills lesson explains it). That's what --target picks. Without it, tsc aims at ES5, the edition of JavaScript from 2009, so the overview's cart.js comes out like this:

var teaPrice = 3;
var cakePrice = "4";
console.log(teaPrice + cakePrice);

Each const became var, the older way to declare a variable. The program does the same thing and prints 34. The next lesson sets the target once, in a settings file, so you don't type it each time.

Types disappear when the code runs

Because emitting removes every type, no type exists while the code runs. You can see this with JavaScript's typeof, which looks at a value while the code runs and names its kind (the Checking types reliably lesson covers it):

1type Price = number;2 3const cakePrice: Price = 4;4console.log(typeof cakePrice);5console.log(typeof Price);

Line 1 names a type, Price, which means a number. Line 3 makes cakePrice a Price and gives it 4. Line 4 prints number: typeof sees the value 4, not the name Price.

Line 5 asks about Price itself, and TypeScript marks it on purpose: 'Price' only refers to a type, but is being used as a value here. In plain words: "Price is only a type, and types don't exist when the code runs". Run it anyway, and line 5 prints undefined, which is what typeof says about a name that doesn't exist. The type Price line was removed, so there's nothing called Price left.

So a type can never change what your code does. The code that runs is the same with or without it. Try it: each button changes line 2. Watch the errors, the line tsc writes, and the output.

1const teaPrice: number = 3;2const cakePrice: number = "4";3console.log(teaPrice + cakePrice);

The first three buttons give three different types, or none. TypeScript's answer changes each time, but tsc writes the same line, const cakePrice = "4";, so the code prints 34 every time. Only the last button changes the value, to the number 4, and only then does the output change, to 7. A type describes a value. It never turns one kind of value into another.

Errors don't stop the output

You saw it in the overview: tsc reported an error and still wrote cart.js. That's on purpose. The two jobs are separate, and by default an error in one doesn't stop the other. The TypeScript team chose this because you often know better than the checker for a moment, like halfway through turning a JavaScript project into TypeScript.

When you'd rather have no JavaScript than JavaScript with a known mistake, add the --noEmitOnError option. An option (or flag) is a setting you add to a command, starting with --. With this one, any error means tsc writes nothing. The playground also shows each command's exit code: a number a command hands back when it finishes. Build scripts read it: 0 means success, and anything else means something went wrong. Try both prices with both commands:

1const teaPrice: number = 3;2const cakePrice: number = "4";3console.log(teaPrice + cakePrice);

With a number on line 2, there's no error, and both commands write cart.js. With text, plain tsc prints the error, still writes the file, and exits with 2. --noEmitOnError prints the same error, writes nothing, and exits with 1.

Many tools do only the second job. Build tools like Vite remove the types and never check them, and leave checking to your editor or to a separate tsc run. This page's Edit & run works the same way: it removes the types and runs the code, which is why the overview's example printed 34 even with its error.

Static checks and runtime checks

There are two moments you can check a value. A static check happens before the code runs: TypeScript reads your code. A runtime check happens while the code runs: your own code looks at a real value. They catch different mistakes. Here is a function that needs both:

1function readQuantity(text: string) {2  const quantity = Number(text);3  if (Number.isNaN(quantity)) {4    return 1;5  }6  return quantity;7}8 9const first = readQuantity("2");10//    ^?11console.log(first);12console.log(readQuantity("two"));

Line 1 declares readQuantity, which takes the text from a quantity box. Line 2 turns it into a number with Number. Line 3 is a runtime check: Number.isNaN asks "is this NaN?". NaN means "not a number", and it's what Number gives back for text like "two". If so, line 4 gives back 1 instead. Otherwise line 6 gives back the quantity.

Line 9 calls it with "2". The query on line 10 shows const first: number: TypeScript worked out that readQuantity always gives back a number. Line 11 prints 2. Line 12 passes "two", and the runtime check makes it print 1. TypeScript couldn't have caught "two": it's text, which is exactly what the function asks for. Only the value is wrong, and values from a shopper only exist while the page runs.

The static check catches a different mistake: a wrong kind of value in your own code.

1function readQuantity(text: string) {2  return Number(text);3}4console.log(readQuantity(2));

Line 4 calls readQuantity(2) with a number. TypeScript marks it on purpose: Argument of type 'number' is not assignable to parameter of type 'string'. An argument is a value you pass in a call, and a parameter is the name that receives it, like text. So: "you passed a number where the function takes text". This happens to print 2 anyway, but the next change to readQuantity might not be so forgiving.

The table below compares the two kinds of check. Read each row as a question, then each kind's answer.

A product from a server, checked both ways

A shop page asks a server for a product, and the server replies with text in a format called JSON (the JSON lesson covers JSON.parse). Real code uses both kinds of check. The static check keeps your code consistent. A runtime check guards the door where outside data comes in. Press each button to change what the server sends:

1type Product = { name: string; price: number };2 3function toProduct(data: { name: string; price: string }): Product {4  const price = Number(data.price);5  if (Number.isNaN(price)) {6    throw new Error(`Bad price for ${data.name}`);7  }8  return { name: data.name, price };9}10 11const reply = '{ "name": "Cake", "price": "4" }';12const cake = toProduct(JSON.parse(reply));13console.log(cake.price + 3);

Read the code from the top:

• Line 1 says what a Product is: a name that is text and a price that is a number.
• Line 3 declares toProduct. It takes the reply's data and promises to give back a Product. TypeScript checks that promise statically: line 8 must build an object with a text name and a number price.
• Lines 4 to 7 are the runtime check. Line 4 turns the price into a number. If that gives NaN, line 6 throws an error, which stops the code with a message (the try, catch & finally lesson shows how to catch it).
• Line 11 is the reply. Line 12 reads it with JSON.parse and turns it into a Product. Line 13 prints the price plus 3.

The list under the code says No errors for every reply. TypeScript can't see what a server will send. With "four" or no price at all, only the check on line 5 notices, and the code stops with Error: Bad price for Cake instead of quietly showing a wrong total. After line 12, the rest of your code can trust cake.price to be a real number, and TypeScript checks that it's used like one.

Common mix-ups

A type annotation is a promise you make to TypeScript. It doesn't change the value:

1const quantity: number = JSON.parse('"2"');2console.log(quantity + 1);

Line 1 reads the JSON text "2" with JSON.parse, which gives back the string "2", and says it's a number. JSON.parse can give back anything, so TypeScript believes you and reports nothing. The annotation is removed before the code runs, so quantity is still text, and line 2 prints 21.

• "tsc runs my code." No. It reads your code and writes JavaScript. A browser or Node runs that JavaScript.
• "An error means no JavaScript is written." No. By default, tsc writes the file anyway. Only --noEmitOnError holds it back.
• "Writing : number turns a value into a number." No. The annotation is removed before the code runs. Use Number(…) to convert, as the 21 example shows.
• "I can check a type with typeof while the code runs." No. typeof sees values, like 4. A name made with type, like Price, is gone by then.
• "With TypeScript, I don't need runtime checks." No. TypeScript checks your code, not the data that arrives while it runs. A shopper's text or a server's reply still needs your own check.
• "Every tool that handles .ts files checks the types." No. Many, like Vite and this page's Edit & run, only remove them. Checking comes from your editor or from tsc.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to try a change: the errors update as you type, and the console shows what it prints. Guess first, then use the hints.

1type Order = { item: string; quantity: number };2 3const order: Order = { item: "Tea", quantity: 2 };4console.log(order.quantity);

1type Order = { item: string; quantity: number }; // removed2 3const order: Order = { item: "Tea", quantity: 2 }; // kept, without ": Order"4console.log(order.quantity); // kept as it is

1function shippingCost(weight: number) {2  return weight * 2;3}4console.log(shippingCost("3"));

1function shippingCost(weight: number) {2  return weight * 2;3}4console.log(shippingCost(3));

1function readQuantity(text: string) {2  return Number(text);3}4console.log(readQuantity("two"));

1function readQuantity(text: string) {2  const quantity = Number(text);3  if (Number.isNaN(quantity)) {4    return 1;5  }6  return quantity;7}8console.log(readQuantity("two"));

const quantity: number = "2";
console.log(quantity);

1const quantity: number = "2"; // an error, so --noEmitOnError writes no cart.js2console.log(quantity);

1const cakePrice: number = "4";2console.log(3 + cakePrice);

1const cakePrice: string = "4";2console.log(3 + cakePrice);

1type Product = { name: string; price: number };2 3const reply = '{ "name": "Cake", "price": "four" }';4const cake: Product = JSON.parse(reply);5console.log(cake.price * 2);

1type Product = { name: string; price: number };2 3const reply = '{ "name": "Cake", "price": "four" }';4const data = JSON.parse(reply);5const price = Number(data.price);6if (Number.isNaN(price)) {7  console.log("Bad price");8} else {9  const cake: Product = { name: String(data.name), price };10  console.log(cake.price * 2);11}

Check your understanding

For each question, keep the moments apart: what tsc says and writes before the code runs, and what the code does when it runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• The TypeScript compiler, tsc, does two jobs: checking reports type errors, and emitting writes plain JavaScript.
• Checking is static: it reads your code without running it, so it checks every line, even code that never runs.
• Emitting removes the types: annotations, type aliases, and the rest. Everything else is copied, so the code does exactly what it did.
• No type exists while the code runs. typeof sees values, and an annotation never converts a value.
• By default, an error doesn't stop tsc from writing JavaScript. --noEmitOnError changes that.
• Static checks catch mistakes in your code. Runtime checks, written by you, catch bad data that arrives while the code runs.

Coming next: Setting up a project. You'll install tsc, write a tsconfig.json settings file, and run TypeScript in your editor and in Node.