TypeScript for JavaScript Developers: A Practical Migration Guide

TypeScript is JavaScript with an optional type system layered on top — it compiles down to plain JS, so adoption can be gradual, file by file, rather than an all-or-nothing rewrite. Here's a practical path for a JavaScript developer picking it up.

The Core Idea: Types Catch Bugs Before Runtime

function greet(name: string): string {
  return `Hello, ${name}`;
}

greet(42); // Error caught at compile time, not discovered in production

In plain JS, that bug either silently produces "Hello, 42" or breaks somewhere downstream in a confusing way. TypeScript catches it the moment you write it, in your editor, before the code ever runs.

Typing Objects with Interfaces

interface User {
  id: number;
  name: string;
  email: string;
  role?: 'admin' | 'member'; // optional, and restricted to these two values
}

function renderUser(user: User) {
  return `${user.name} (${user.role ?? 'member'})`;
}

Union types like 'admin' | 'member' are one of TypeScript's most immediately useful features — they make invalid values a compile error instead of a runtime surprise.

Generics: Reusable, Type-Safe Functions

function firstItem<T>(arr: T[]): T | undefined {
  return arr[0];
}

firstItem([1, 2, 3]);        // inferred as number | undefined
firstItem(['a', 'b']);       // inferred as string | undefined

Without generics, you'd either lose type safety entirely (typing the parameter as any[]) or write a nearly-identical function per type — generics give you one function that stays fully type-safe for whatever type it's called with.

Migrating an Existing JS File Gradually

// Rename utils.js to utils.ts — TypeScript starts checking it immediately,
// but with looser rules by default (allowJs, implicit any) until you tighten config.

// tsconfig.json — start lenient, tighten over time
{
  "compilerOptions": {
    "strict": false,     // flip to true once the codebase is mostly typed
    "allowJs": true,
    "checkJs": false
  }
}

Setting strict: true on day one of migrating a large existing codebase usually produces hundreds of errors at once — demoralizing and not actually useful. Migrate incrementally, file by file, then tighten strict mode only once the bulk of the codebase already has real types.

Where TypeScript Pays Off Most

The value compounds with codebase size and team size — a solo weekend script gets little benefit, but a shared API contract between a frontend and backend team, or a component library with dozens of consumers, catches an enormous number of real integration bugs at compile time instead of in production.