TypeScript Essentials for Real Apps

Why types pay for themselves

If you are coming from plain JavaScript for the browser, TypeScript can feel like extra homework. It is not. It is a contract you write once that the compiler then enforces on every line you touch afterward. The bugs it catches are the boring, expensive ones: a typo in a property name, a function called with the wrong argument, a value that might be null and you forgot.

The deal is simple. You describe the shape of your data, and TypeScript checks your code against that shape at edit time, in your editor, before you ever run it. The cost is a few annotations. The payoff is a whole class of runtime errors that simply cannot happen.

Types are documentation that cannot go out of date, because the compiler refuses to let it.

Structural typing: shapes, not names

The single most important idea in TypeScript is structural typing. A value fits a type if it has the right shape, regardless of what it is named or where it came from. This is different from languages like Java where you must explicitly declare that a class implements an interface.

interface Point {
  x: number;
  y: number;
}

function distance(p: Point): number {
  return Math.sqrt(p.x * p.x + p.y * p.y);
}

// This object was never declared as a Point,
// but it has the right shape, so it fits.
const here = { x: 3, y: 4, label: "home" };
distance(here); // 5, extra fields are fine when passed via a variable

Because TypeScript checks shapes, you can model your domain naturally and let values flow through your code without endless casting. Two objects from completely different parts of the app are interchangeable the moment they share a shape.

Interfaces vs types, and when to reach for each

Beginners burn a lot of energy on this question. The honest answer: for object shapes they are nearly interchangeable. Pick one and stay consistent. The differences matter only at the edges.

The bug an annotation catches

Here is the value proposition in two code blocks. First, untyped JavaScript that looks correct and ships a bug to production:

function priceWithTax(item) {
  return item.price * (1 + item.taxRate);
}

// Somewhere far away, a caller passes the wrong field name.
priceWithTax({ price: 100, tax_rate: 0.2 });
// returns NaN, taxRate is undefined, 1 + undefined is NaN
// No error. The receipt just says NaN. You find out from a customer.

Now the same code with a type. The mistake is impossible to make; the editor refuses it:

interface LineItem {
  price: number;
  taxRate: number;
}

function priceWithTax(item: LineItem): number {
  return item.price * (1 + item.taxRate);
}

priceWithTax({ price: 100, tax_rate: 0.2 });
// Error: Object literal may only specify known properties,
// and tax_rate does not exist in type LineItem. Did you mean taxRate?

Unions, literal types, and narrowing

Union types let a value be one of several things, and literal types pin a value to an exact string or number. Together they model state precisely. A request is loading or success or error, never some illegal in-between.

type Status = "idle" | "loading" | "success" | "error";

type Result =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(r: Result): string {
  // Narrowing: TypeScript figures out which member you are in
  // from the discriminant field, then unlocks the right fields.
  switch (r.status) {
    case "loading":
      return "Loading...";
    case "success":
      return r.data.join(", "); // r.data is safe here
    case "error":
      return r.message; // r.message is safe here
  }
}

Narrowing is how TypeScript turns a broad type into a specific one inside a branch. A typeof check, a switch on a discriminant, an if (value) guard, or an in operator all narrow. When the obvious checks are not enough, write a type guard: a function whose return type is a type predicate.

interface Cat { meow: () => void; }
interface Dog { bark: () => void; }

// The return annotation pet is Cat is the type predicate.
function isCat(pet: Cat | Dog): pet is Cat {
  return "meow" in pet;
}

function speak(pet: Cat | Dog): void {
  if (isCat(pet)) {
    pet.meow(); // narrowed to Cat
  } else {
    pet.bark(); // narrowed to Dog
  }
}

Generics: write it once, type it for everything

Generics are types with a hole in them. You write a function or container once, and the caller fills in the concrete type. The classic motivation: a function that returns whatever you give it should not flatten your type to any.

// T is a placeholder filled in at the call site.
function first<T>(items: T[]): T | undefined {
  return items[0];
}

const n = first([1, 2, 3]);        // n: number | undefined
const s = first(["a", "b"]);       // s: string | undefined

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

Utility types and as const

TypeScript ships utility types that transform existing types so you do not redefine the same shape five times. These are the four you will use weekly:

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

type PublicUser = Omit<User, "passwordHash">;
type UserUpdate = Partial<Pick<User, "name" | "email">>;
type UsersById = Record<string, PublicUser>;

const patch: UserUpdate = { name: "Sri" }; // email optional, id not allowed

Then there is as const, which freezes a value into its most specific, readonly literal type. Without it, { role: "admin" } is typed as { role: string }. With it, the role is the literal "admin". This is how you derive a union from a real array of values.

const ROLES = ["admin", "editor", "viewer"] as const;

// Derive a union type from the data, one source of truth.
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function grant(role: Role): void {
  // Adding a role to ROLES updates the type automatically.
}

Typing async code and API responses

Async functions return a Promise<T>, and await unwraps it to T. Typing the resolved shape is what makes a fetch chain pleasant: every .then and every field access downstream is checked.

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

async function getUser(id: string): Promise<User> {
  const res = await fetch("/api/users/" + id);
  if (!res.ok) {
    throw new Error("Request failed: " + res.status);
  }
  // DANGER: res.json() is typed as any (really Promise<any>).
  // This annotation is a promise to the compiler, not a guarantee.
  const data = (await res.json()) as User;
  return data;
}

Validate untrusted input at the boundary with zod

Because types vanish at runtime, anything crossing a boundary, an API response, a form submission, a webhook, a parsed JSON file, must be validated by code that actually runs. Zod lets you declare a schema once, validate against it at runtime, and infer the static type for free. One source of truth, two guarantees.

import { z } from "zod";

const UserSchema = z.object({
  id: z.string(),
  name: z.string().min(1),
  email: z.string().email(),
});

// Infer the static type from the schema, never write it twice.
type User = z.infer<typeof UserSchema>;

async function getUser(id: string): Promise<User> {
  const res = await fetch("/api/users/" + id);
  if (!res.ok) throw new Error("Request failed: " + res.status);

  // parse throws if the data does not match, a real runtime check.
  return UserSchema.parse(await res.json());
}

The same pattern is exactly how robust forms and validation in React work: one schema validates the user input and types the parsed result. Validate at the edge, and the entire interior of your app can trust its types completely.

1. 1

   Define the schema

   Declare the expected shape with zod once, at the module that owns the boundary.

2. 2

   Infer the type

   Use z.infer so the static type and the runtime check can never drift apart.

3. 3

   Parse at the edge

   Call .parse (throws) or .safeParse (returns a result) the moment data arrives.

4. 4

   Trust the interior

   Past the boundary, every value is both validated and typed, no more casting.

Why any is a trap, and unknown is the escape hatch

When TypeScript fights you, the tempting fix is to type something as any. Resist it. any does not mean any value, it means turn off the type checker for this value and everything it touches. It silently spreads through your code, disabling exactly the safety you installed TypeScript to get.

function parse(json: string): unknown {
  return JSON.parse(json); // genuinely unknown shape
}

const data = parse("{}");

// data.name; // Error: data is of type unknown

if (typeof data === "object" && data !== null && "name" in data) {
  // Narrowed enough to be safe.
  console.log((data as { name: unknown }).name);
}
// Better still: hand the value to a zod schema and let it narrow for you.

A pragmatic strict tsconfig

Most of TypeScript's value is locked behind compiler flags that are off by default in old projects. The single best switch is strict: true, which turns on a bundle of checks including strictNullChecks, the one that forces you to handle null and undefined. Start strict on day one; retrofitting it later is painful.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "esModuleInterop": true
  }
}

Common mistakes that cost hours

1. Reaching for any when the compiler complains. You are not fixing the error, you are hiding it and every error downstream of it. Use unknown and narrow.
2. Casting with as to silence an error. as is a promise, not a check, data as User tells the compiler to trust you even when you are wrong. Reserve it for cases the compiler genuinely cannot see.
3. Trusting API responses because you typed them. The annotation is erased at runtime; validate with zod at the boundary or you are typing hope.
4. Skipping strict mode to move faster. Without strictNullChecks, undefined sneaks everywhere and you get the exact runtime crashes types were meant to prevent.
5. Re-declaring shapes that already derive. If you write a zod schema and a separate interface for the same thing, they will drift. Infer the type from the schema instead.
6. Over-generic code. Generics with three type parameters and constraints nobody reads are harder to maintain than a little duplication. Generalize only when a real second use case appears.

Takeaways and where to go next

TypeScript is most valuable where it meets a framework. Take these foundations into React fundamentals: hooks and rendering to type props, state, and effects, and into forms and validation in React to see the zod-at-the-boundary pattern run end to end. If any of the language underneath still feels shaky, circle back to JavaScript for the browser first.

• Turn on strict in one real project and fix the errors, that is the fastest way to internalize null safety.
• Replace one as-cast API call with a zod schema and feel the difference at the boundary.
• Practice narrowing: model a request as a discriminated union and render each state.