楊東霖

Posted on Mar 25 • Originally published at devplaybook.cc

TypeScript Beginner's Guide: Migrate from JavaScript the Right Way

#webdev #javascript #programming #tutorial

TypeScript is JavaScript with a safety net. It doesn't replace JavaScript — it compiles down to it. But between writing your code and that compilation step, TypeScript checks your work: it catches the typo in that property name, the function call with the wrong argument type, the variable that might be undefined when you're treating it as a string. It finds bugs before they find you.

This guide assumes you know JavaScript. We'll cover the key TypeScript concepts, then walk through a practical migration from an existing JS project — the right way, without breaking everything in one go.

TL;DR

TypeScript adds static types to JavaScript, catching bugs at compile time instead of runtime
Install with npm install -D typescript and configure with tsconfig.json
Core types: string, number, boolean, string[], Record<K, V>, union types (string | number)
interface and type are both valid — interface for object shapes, type for unions/primitives
Migrate JS projects incrementally: start with allowJs: true, then add types file by file
Don't fight TypeScript — when you find yourself using any everywhere, step back and reconsider your types

Why TypeScript Exists

JavaScript is dynamically typed. Type errors are runtime errors. This means bugs like the following are caught only when a user hits that code path:

// JavaScript — this looks fine until it runs
function greetUser(user) {
  return `Hello, ${user.nme}!`; // Typo: 'nme' instead of 'name'
}

greetUser({ name: "Alice" });
// → "Hello, undefined!" — silently wrong, no error thrown

TypeScript catches this before you even run the code:

// TypeScript — caught at compile time
interface User {
  name: string;
  email: string;
}

function greetUser(user: User): string {
  return `Hello, ${user.nme}!`;
  //                   ^^^
  // Error: Property 'nme' does not exist on type 'User'. Did you mean 'name'?
}

At small scale, this might seem like overkill. At large scale — big codebases, multiple developers, code that hasn't been touched in six months — TypeScript is the difference between confident refactoring and terrified guessing.

JavaScript pain points TypeScript solves:

Typos in property names — caught immediately
Wrong argument types — caught at the call site
Missing required properties — caught when constructing objects
Unsafe null and undefined access — caught with strict null checks
Broken refactoring — rename a property and TypeScript tells you everywhere it needs to change

Setting Up TypeScript

# In an existing project
npm install --save-dev typescript

# Generate a tsconfig.json
npx tsc --init

A sensible starting tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

The most important option is "strict": true. It enables a group of checks:

Strict flag	What it catches
`strictNullChecks`	Prevents using `null`/`undefined` without checking first
`noImplicitAny`	Requires explicit types when TypeScript can't infer
`strictFunctionTypes`	Stricter function argument compatibility
`strictPropertyInitialization`	Class properties must be initialized in constructor

Start with strict: true on new projects. For migrations, you may need to enable these one at a time.

Compile and watch:

npx tsc                    # one-time compile
npx tsc --watch            # watch mode — recompiles on file changes
npx tsc --noEmit           # type-check only, don't emit JS (useful in CI)

Basic Types

Primitives

let name: string = "Alice";
let age: number = 30;
let isActive: boolean = true;
let nothing: null = null;
let notDefined: undefined = undefined;
let bigInt: bigint = 9007199254740991n;

TypeScript infers types from assignments, so you often don't need to annotate:

let name = "Alice";     // TypeScript infers: string
let age = 30;           // TypeScript infers: number
let isActive = true;    // TypeScript infers: boolean

Annotate explicitly when:

Declaring a variable without initializing it
The inferred type is too broad
Writing function signatures

Arrays and Tuples

// Arrays
let names: string[] = ["Alice", "Bob"];
let scores: number[] = [100, 95, 87];
let mixed: (string | number)[] = ["Alice", 42];

// Generic array syntax (equivalent)
let names2: Array<string> = ["Alice", "Bob"];

// Tuples — fixed-length arrays with known types at each position
let point: [number, number] = [10, 20];
let entry: [string, number] = ["Alice", 30];

Objects

// Inline object type
let user: { name: string; age: number; email?: string } = {
  name: "Alice",
  age: 30
  // email is optional (marked with ?)
};

Interfaces vs Types

Both define the shape of an object. The practical difference is small; choose one and be consistent.

// Interface
interface User {
  id: string;
  name: string;
  email: string;
  role: "admin" | "user" | "viewer";
  createdAt: Date;
  bio?: string;       // optional property
  readonly apiKey: string;  // can't be reassigned after creation
}

// Type alias (equivalent for object shapes)
type UserType = {
  id: string;
  name: string;
  email: string;
};

When to use interface: Object shapes, especially when you expect them to be extended or implemented by classes. Interfaces support declaration merging (useful for augmenting third-party types).

When to use type: Union types, intersection types, mapped types, and aliases for primitives or tuples.

// Type does these well; interface doesn't
type Status = "pending" | "active" | "suspended";
type ID = string | number;
type Point = [number, number];
type StringMap = Record<string, string>;

// Intersection (combining types)
type AdminUser = User & { permissions: string[] };

// Union (either of these)
type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;

Union Types and Type Narrowing

Union types say "this value can be one of several types." TypeScript requires you to handle each case:

function formatId(id: string | number): string {
  if (typeof id === "number") {
    return id.toString().padStart(8, "0");  // TypeScript knows id is number here
  }
  return id.toUpperCase();  // TypeScript knows id is string here
}

This narrowing also works with instanceof, in, and discriminated unions:

interface Circle {
  shape: "circle";  // literal type as discriminant
  radius: number;
}

interface Rectangle {
  shape: "rectangle";
  width: number;
  height: number;
}

type Shape = Circle | Rectangle;

function getArea(shape: Shape): number {
  switch (shape.shape) {
    case "circle":
      return Math.PI * shape.radius ** 2;  // TypeScript knows: Circle
    case "rectangle":
      return shape.width * shape.height;   // TypeScript knows: Rectangle
  }
}

Discriminated unions are powerful: the shared shape field (with literal types) lets TypeScript narrow the type automatically inside each case.

Optional Properties and Non-Null Assertion

interface Config {
  apiUrl: string;
  timeout?: number;     // optional — may be undefined
  debug?: boolean;
}

function createClient(config: Config) {
  // TypeScript error: 'timeout' might be undefined
  const ms = config.timeout * 1000;

  // Correct: use optional chaining and nullish coalescing
  const ms = (config.timeout ?? 30) * 1000;

  // Or: check first
  if (config.timeout !== undefined) {
    const ms = config.timeout * 1000;  // now TypeScript knows it's a number
  }
}

The non-null assertion operator (!) tells TypeScript you're certain a value isn't null/undefined. Use sparingly — it bypasses the check:

// Use only when you KNOW it exists
const element = document.getElementById("app")!;
element.classList.add("loaded");

Generics: Writing Reusable Code

Generics let you write functions and types that work with multiple types while preserving type information:

// Without generics — loses type info
function firstItem(arr: any[]): any {
  return arr[0];
}

const result = firstItem(["Alice", "Bob"]);
// result is 'any' — TypeScript can't help you

// With generics — type preserved
function firstItem<T>(arr: T[]): T | undefined {
  return arr[0];
}

const result = firstItem(["Alice", "Bob"]);
// result is 'string | undefined' — TypeScript knows!

const count = firstItem([1, 2, 3]);
// count is 'number | undefined'

A practical generic: a typed API response wrapper:

interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
  timestamp: string;
}

interface User {
  id: string;
  name: string;
  email: string;
}

async function fetchUser(id: string): Promise<ApiResponse<User>> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

const result = await fetchUser("123");
console.log(result.data.name);   // TypeScript knows this is a string
console.log(result.data.nme);    // Error: Property 'nme' does not exist

Generic constraints — require the generic type to have certain properties:

// T must have an 'id' property
function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
  return items.find(item => item.id === id);
}

TypeScript with React

For React components, use the React-specific types:

import React, { useState, useEffect } from 'react';

interface UserCardProps {
  userId: string;
  showEmail?: boolean;
  onDelete?: (id: string) => void;
}

const UserCard: React.FC<UserCardProps> = ({ userId, showEmail = false, onDelete }) => {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchUser(userId)
      .then(result => setUser(result.data))
      .finally(() => setLoading(false));
  }, [userId]);

  if (loading) return <div>Loading...</div>;
  if (!user) return <div>User not found</div>;

  return (
    <div>
      <h2>{user.name}</h2>
      {showEmail && <p>{user.email}</p>}
      {onDelete && (
        <button onClick={() => onDelete(userId)}>Delete</button>
      )}
    </div>
  );
};

Migrating a JavaScript Project

The recommended approach: incremental migration. Never do a big-bang rewrite.

Step 1: Add TypeScript without breaking anything

Install dependencies:

npm install --save-dev typescript @types/node
npx tsc --init

Set up tsconfig.json for migration mode:

{
  "compilerOptions": {
    "allowJs": true,           // Allow .js files alongside .ts
    "checkJs": false,          // Don't type-check .js files yet
    "strict": false,           // Start permissive
    "outDir": "./dist",
    "rootDir": "./src",
    "target": "ES2020",
    "module": "commonjs",
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

With allowJs: true, TypeScript compiles both .js and .ts files. Your existing code still works.

Step 2: Rename files one at a time

Start with utility files that have no dependencies (they're the easiest):

mv src/utils/formatDate.js src/utils/formatDate.ts

Now add types to that file:

// Before (JavaScript)
function formatDate(date, format) {
  if (!date) return '';
  const d = new Date(date);
  // ...
}

// After (TypeScript)
type DateInput = Date | string | number;
type DateFormat = 'short' | 'long' | 'iso';

function formatDate(date: DateInput, format: DateFormat = 'short'): string {
  if (!date) return '';
  const d = new Date(date);
  // ...
}

Step 3: Add types for third-party libraries

Most popular libraries have community-maintained type definitions:

npm install --save-dev @types/express @types/lodash @types/uuid

If a library doesn't have types (rare for popular libraries), create a declaration file:

// src/types/untyped-library.d.ts
declare module 'some-untyped-library' {
  export function doThing(input: string): number;
  export const VERSION: string;
}

Step 4: Enable stricter checking progressively

Once the majority of files are converted to .ts:

{
  "compilerOptions": {
    "allowJs": false,          // Only .ts now
    "checkJs": false,
    "strict": false,
    "noImplicitAny": true,     // Enable one at a time
    "strictNullChecks": true
  }
}

Each flag you enable will reveal new type errors. Fix them file by file. Enable strict: true as the final step.

Common TypeScript Gotchas

The any escape hatch: any disables type checking for a value. It's tempting when migrating, but overuse defeats the purpose. Use unknown instead when you genuinely don't know the type — it forces you to narrow before using:

// Bad: any disables all checking
function parse(input: any) {
  return input.toUpperCase();  // No error even if input is a number
}

// Better: unknown forces you to check
function parse(input: unknown): string {
  if (typeof input === 'string') {
    return input.toUpperCase();  // Safe — we verified it's a string
  }
  throw new Error(`Expected string, got ${typeof input}`);
}

Type assertions vs type guards: as forces a type assertion. Type guards are safer because they actually check:

// Assertion — no runtime check, can lie to TypeScript
const user = response as User;

// Guard — actually verifies the shape at runtime
function isUser(obj: unknown): obj is User {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj &&
    'name' in obj &&
    'email' in obj
  );
}

if (isUser(response)) {
  console.log(response.name);  // TypeScript trusts the guard
}

Enum pitfalls: TypeScript enum has some surprising runtime behavior. Prefer union types or const objects:

// Avoid regular enums (they have runtime overhead and numeric index issues)
enum Direction { Up, Down, Left, Right }

// Prefer: union type (zero runtime overhead)
type Direction = 'up' | 'down' | 'left' | 'right';

// Or: const object (has the value object available at runtime if needed)
const Direction = {
  Up: 'up',
  Down: 'down',
  Left: 'left',
  Right: 'right',
} as const;
type Direction = typeof Direction[keyof typeof Direction];

TypeScript has a learning curve, but it pays for itself quickly. The first week you find a bug in code review that TypeScript would have caught in two seconds, you'll understand why so many teams have made it their default.

Start with a new file, add types gradually, and let TypeScript guide you. The goal isn't type perfection — it's catching the bugs that would otherwise reach production.

Level Up Your Dev Workflow

Found this useful? Explore DevPlaybook — cheat sheets, tool comparisons, and hands-on guides for modern developers.

🛒 Get the DevToolkit Starter Kit on Gumroad — 40+ browser-based dev tools, source code + deployment guide included.

DEV Community