TypeScript Best Practices 🏆

1. Turn On Strict Mode

The single highest-value thing you can do is set "strict": true in your tsconfig.json. That one flag switches on a whole family of checks — including strictNullChecks (you can't accidentally use a value that might be null) and noImplicitAny (TypeScript refuses to silently fall back to any). Without strict mode, TypeScript is barely more than a fancy linter; with it, it actually proves your code can't hit whole classes of bugs.

Here's a sensible starting tsconfig.json. Copy it, then read why each line earns its place.

{
  "compilerOptions": {
    "strict": true,                       // ✅ the big one: turns on all strict checks
    "noUncheckedIndexedAccess": true,     // arr[i] is T | undefined, not just T
    "noImplicitReturns": true,            // every code path must return
    "noFallthroughCasesInSwitch": true,   // a missing 'break' is an error
    "noUnusedLocals": true,               // dead variables become errors
    "forceConsistentCasingInFileNames": true, // ./User vs ./user can't differ
    "target": "ES2020",
    "module": "ESNext",
    "skipLibCheck": true                  // don't re-check node_modules .d.ts files
  }
}

2. Avoid any — Reach for unknown

any means "turn off type checking for this value." It's contagious: anything you touch through an any becomes any too, and your safety net quietly disappears. The honest alternative is unknown — it also accepts any value, but it won't let you do anything with that value until you've narrowed it (proved what it is with a check like typeof x === "string"). Run the worked example below: it shows the exact runtime crash that any waves through and unknown prevents.

// The 'any' escape hatch turns TypeScript OFF for that value.
// Here is the SAME logic, before and after, run as plain JS so you
// can see the runtime behaviour the types are protecting you from.

// ❌ BEFORE: typed as 'any' — the compiler stops checking.
//    function parse(raw: any) {            <-- 'any' = "trust me"
//      return raw.user.name.toUpperCase(); <-- no warning, may crash
//    }
function parseUnsafe(raw) {
  // With 'any', TS lets you reach into anything. At runtime it blow
...

Your turn. The function below receives an unknown value and must narrow it before use. Fill in the three blanks marked ___ using the hints, then run it and check the output.

// 🎯 YOUR TURN #1 — kill the 'any'. Replace each ___ then press Run.
// This file runs as JS; the comments show the TypeScript you'd write.

// A function received an 'unknown' value from JSON.parse(...).
// In TS its signature is:  function format(value: unknown): string
function format(value) {
  // 1) Narrow to a number FIRST. Fill in the type to compare against.
  if (typeof value === ___) {        // 👉 the word "number" in quotes
    return "£" + value.toFixed(2);   // safe: value is a nu
...

3. Let Inference Work — Don't Over-Annotate

TypeScript reads your values and figures out their types automatically. Writing const name: string = "Alice" is just repeating yourself — const name = "Alice" already gives name the type string. Over-annotating adds noise and, worse, can drift out of sync with the real value. The skill is knowing where to annotate: at the boundaries (function parameters and exported return types) where TypeScript can't read your intent.

// Let inference work. Re-typing what TS already knows is just noise.
console.log("=== Don't repeat what TypeScript can see ===");

// ❌ Over-annotated — every ': type' here is redundant:
//    const name: string = "Alice";
//    const tags: string[] = ["a", "b"];
//    const total: number = price * qty;

// ✅ Inferred — TS reads the value and gives it the exact type:
const name = "Alice";          // inferred: string
const tags = ["a", "b"];       // inferred: string[]
const price = 9.99, qty =
...

4. Immutability: readonly and as const

If a value shouldn't change, say so in the type — the compiler will then stop anyone (including future-you) from mutating it by accident. readonly marks an individual property or a whole array as look-but-don't-touch. as const goes further: it freezes an object/array literal so its values become exact, narrow, read-only types instead of being widened to string or number.

// readonly on a property and on an array
interface Point { readonly x: number; readonly y: number; }
const p: Point = { x: 1, y: 2 };
// p.x = 9;                       // ❌ error: x is read-only

function sum(nums: readonly number[]) {
  // nums.push(0);                // ❌ error: can't mutate a readonly array
  return nums.reduce((a, b) => a + b, 0);
}

// as const freezes a literal and narrows its types:
const ROUTES = ["/home", "/about"] as const;
// type is  readonly ["/home", "/about"]  — not  string[]
type Route = (typeof ROUTES)[number];   // "/home" | "/about"

const CONFIG = { env: "prod", retries: 3 } as const;
// CONFIG.retries = 5;            // ❌ error: read-only

5. Prefer Unions Over Enums

For a fixed set of options, a string-literal union like type Role = "admin" | "editor" | "viewer" is usually the better tool than an enum. Unions have zero runtime footprint (an enum emits real JavaScript), the values are just the strings — so they read cleanly in logs, JSON, and APIs — and they autocomplete everywhere. Run this to see a union in action, then read the note on when an enum still earns its keep.

// Prefer a string-literal UNION over an enum for most "one of these" sets.
console.log("=== Union of string literals ===");

// ✅ A union type (in TS):  type Role = "admin" | "editor" | "viewer";
//    - zero runtime code  - autocompletes  - values ARE the strings
const ROLES = ["admin", "editor", "viewer"];

function can(role, action) {
  // Each branch is checked against the union; a typo like "admn" is a TS error.
  if (role === "admin")  return true;
  if (role === "editor") return action !
...

6. Type Your Boundaries & Derive With Utility Types

Annotate the edges of your code — function parameters and exported return types — because that's the contract other code relies on. And when you need a variation of a shape you already have, derive it with a utility type instead of re-typing the fields by hand. The big four: Partial<T> (all fields optional), Pick<T, K> (keep some keys), Omit<T, K> (drop some keys), and Record<K, V> (a map). Derived types stay in sync automatically when the source changes.

// One source of truth:
interface User { id: string; name: string; email: string; role: "admin" | "user"; }

// Derive everything else from it — never re-type the fields:
type NewUser    = Omit<User, "id">;            // everything except id
type UserPatch  = Partial<NewUser>;            // every field optional (for updates)
type UserCard   = Pick<User, "name" | "role">; // just the bits a card shows
type UsersById  = Record<string, User>;        // { [id]: User }

// Type the BOUNDARY of an exported function (params + return):
export function createUser(input: NewUser): User {
  return { id: crypto.randomUUID(), ...input };
}

Now you try. Fill in the utility-type names in the comments below, then run it to confirm the derived shapes line up at runtime.

// 🎯 YOUR TURN #2 — derive, don't duplicate. Fill in the ___ comments.
// (Runs as JS; the // TS: lines show the real TypeScript you'd write.)

// You already have one source-of-truth shape:
//    interface User { id: string; name: string; email: string; }
//
// You need a "new user" shape that is User WITHOUT the id.
// Don't re-type the fields by hand — derive it with a utility type.

// 1) The form that creates a user. In TS you'd write:
//    type NewUser = ___<User, "id">;
//    👉 the uti
...

// 🎯 MINI-CHALLENGE: a type-safe API result handler
// Model a fetch result as a discriminated union and handle every case.
//
// In TypeScript you'd define:
//    type Result =
//      | { status: "loading" }
//      | { status: "success"; data: string[] }
//      | { status: "error"; message: string };
//
// Your job (here, as runnable JS):
// 1. Write a function render(result) that switches on result.status.
// 2. "loading" -> return "Loading...";
//    "success" -> return "Got " + result.da
...