TypeScript is JavaScript with types. You write the same code, but you add type annotations that tell the compiler what kind of data each variable, function parameter, and return value should be.

The compiler catches mistakes before your code runs. Instead of finding bugs in production, you find them in your editor with a red squiggly line.

The problem TypeScript solves

// JavaScript — this runs fine, then crashes at runtime
function getUser(id) {
  return fetch(`/api/users/${id}`);
}

// Somewhere else in the codebase, months later:
getUser();           // ❌ Forgot the id — no error until runtime
getUser("abc");      // ❌ Passed a string instead of number — no error
user.naem;           // ❌ Typo — no error until runtime

// TypeScript — catches all of these immediately
function getUser(id: number): Promise<User> {
  return fetch(`/api/users/${id}`);
}

getUser();           // ❌ Error: Expected 1 argument, got 0
getUser("abc");      // ❌ Error: Argument of type 'string' is not assignable to 'number'
user.naem;           // ❌ Error: Property 'naem' does not exist. Did you mean 'name'?

You see these errors in your editor, before you even save the file.

What TypeScript adds

// Type annotations
let name: string = "Alice";
let age: number = 30;
let active: boolean = true;
let tags: string[] = ["dev", "admin"];

// Function types
function greet(name: string): string {
  return `Hello, ${name}!`;
}

// Object types (interfaces)
interface User {
  id: number;
  name: string;
  email: string;
  role: "admin" | "user";    // Union type — only these two values
  bio?: string;               // Optional
}

// Use the interface
function createUser(data: User): void {
  // TypeScript knows exactly what fields 'data' has
  console.log(data.name);    // ✅ Autocomplete works
  console.log(data.phone);   // ❌ Error: 'phone' doesn't exist on User
}

TypeScript = JavaScript + types

Every valid JavaScript file is valid TypeScript. You can adopt it gradually:

// This is valid TypeScript (no types added)
function add(a, b) {
  return a + b;
}

// This is better TypeScript (types added)
function add(a: number, b: number): number {
  return a + b;
}

TypeScript compiles down to plain JavaScript. Browsers and Node.js run the compiled output — they never see the types.

Getting started (5 minutes)

# Install
npm install -D typescript

# Initialize (creates tsconfig.json)
npx tsc --init

# Compile
npx tsc

# Or use ts-node to run directly
npx ts-node src/index.ts

Most frameworks handle this for you:

• Next.js: built-in TypeScript support, just use .tsx files
• Vite: npm create vite@latest my-app -- --template react-ts
• Node.js: use tsx — npx tsx src/index.ts

The most useful types

// Primitives
string, number, boolean, null, undefined

// Arrays
string[], number[], Array<string>

// Objects
{ name: string; age: number }

// Union (one of several types)
string | number
"success" | "error" | "pending"

// Any (escape hatch — avoid when possible)
any

// Unknown (safer than any)
unknown

// Generics
function first<T>(arr: T[]): T {
  return arr[0];
}
first([1, 2, 3]);        // Returns number
first(["a", "b", "c"]);  // Returns string

// Utility types
Partial<User>       // All fields optional
Required<User>      // All fields required
Pick<User, "name" | "email">  // Only these fields
Omit<User, "password">        // All except these
Record<string, number>        // { [key: string]: number }

For the full reference, see the TypeScript cheat sheet.

Why developers love TypeScript

1. Autocomplete everywhere. Your editor knows every field, method, and parameter. No more guessing.
2. Catch bugs before runtime. Typos, wrong types, missing fields — caught instantly.
3. Self-documenting code. Types tell you what a function expects and returns. No need to read the implementation.
4. Refactoring confidence. Rename a field and TypeScript shows you every place that needs updating.
5. Better collaboration. New team members can understand the codebase faster because types explain the data structures.

Common complaints (and responses)

“It’s too verbose” — Use type inference. TypeScript infers most types automatically:

const name = "Alice";     // TypeScript knows this is a string
const nums = [1, 2, 3];  // TypeScript knows this is number[]

“It slows me down” — It slows you down for 5 minutes now, saves you 5 hours of debugging later.

“I can just use JSDoc” — You can, but TypeScript’s type system is far more powerful and better supported by editors.

Should you use TypeScript?

For any project that will be maintained for more than a week, or worked on by more than one person: yes. The initial setup cost is tiny compared to the bugs it prevents.

Start by renaming .js to .ts and fixing errors one file at a time. You don’t have to convert everything at once.