Why TypeScript?

Imagine an online shop where a function formatPrice(price) has worked perfectly for months. One day the price arrives from a form as the string '4.5' instead of a number, and the page breaks with TypeError: price.toFixed is not a function. The customer saw the bug before the developer did. TypeScript exists so that you, not your users, find such bugs — right in your editor, the moment you type them.

What is TypeScript?

In JavaScript, types are checked dynamically — only when a line actually runs. In TypeScript they are checked statically — by reading the code, without running it. You write the type after a colon; this is called a type annotation: price: number means “price is always a number”. If you pass a string anywhere, the compiler tells you at once:

function formatPrice(price: number): string {
  return price.toFixed(2) + ' AZN';
}

console.log(formatPrice(4.5));
console.log(formatPrice('4.5'));

shop.ts:6:25 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

6 console.log(formatPrice('4.5'));
                          ~~~~~

From TypeScript to JavaScript

Browsers and Node.js really understand only JavaScript. That is why the TypeScript compiler, tsc, does two jobs: it checks the types, and it emits ordinary JavaScript in which all the types are simply erased. Here is a small file and the JavaScript that tsc produces from it:

type User = { name: string; age: number };

export function greet(user: User): string {
  return `Hello, ${user.name}! You are ${user.age}.`;
}

const aysel: User = { name: 'Aysel', age: 14 };
console.log(greet(aysel));

Hello, Aysel! You are 14.

export function greet(user) {
    return `Hello, ${user.name}! You are ${user.age}.`;
}
const aysel = { name: 'Aysel', age: 14 };
console.log(greet(aysel));

What types give you

• Bugs are caught early: a typo in a property name, a wrong argument or a forgotten null check is found before the program runs.
• A smart editor: because the editor knows what every value is, autocompletion, go-to-definition and safe renaming across the whole project just work.
• Types work as documentation: the header formatPrice(price: number): string tells you how to use the function without reading its body.
• Safe changes in big projects: change a function's parameters and the compiler lists every place that has to be updated.

Setting up a project

1. 1
   Install TypeScript

   In the project folder, run npm install --save-dev typescript. The compiler goes into node_modules, and you call it with npx tsc.

2. 2
   Create the config file

   npx tsc --init creates a tsconfig.json file with recommended settings.

3. 3
   Write the code

   Put your code in src/index.ts.

4. 4
   Compile and run

   npx tsc checks the whole project and writes the JavaScript to dist/; then run it with node dist/index.js.

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist"
  }
}

Running .ts files directly

Modern Node.js (version 22.18 and newer, including Node.js 24) can run a .ts file directly: node index.ts. It uses type stripping: Node.js simply cuts the types out and runs the JavaScript that remains. The tsx tool does the same job in older versions of Node.js too.

node src/index.ts      # Node.js 22.18+: strip the types and run
npx tsx src/index.ts   # tsx: run TypeScript on older Node.js too
npx tsc --noEmit       # only check the types, write no files