TypeScript: Understanding Interfaces and Types

One of the most common questions for developers transitioning from JavaScript to TypeScript is: should I use an Interface or a Type alias? While they often achieve the same results, understanding their subtle differences and specific use cases is key to writing clean, maintainable, and scalable TypeScript code.

The Fundamentals of Types and Interfaces

At their core, both constructs are used to define the shape of an object or a contract for your data.

Type Aliases are exactly what they sound like: a name for any type. They can represent primitives, unions, tuples, and even complex objects.

type UserID = string | number;
type Point = { x: number; y: number; };

Interfaces, on the other hand, are specifically designed to describe object shapes and class contracts. They are more focused on the structure of data structures and OOP (Object Oriented Programming) patterns.

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

Key Differences and Capabilities

Declaration Merging

One of the most significant differences is that Interfaces support 'declaration merging'. If you define an interface with the same name multiple times, TypeScript will automatically merge them into a single definition. This is extremely useful when working with third-party libraries where you might need to extend an existing global definition.

interface Window {
  analyticsToken: string;
}

// Now the Window object has analyticsToken without errors

Types do not support this. If you try to define the same type name twice, the compiler will throw an error.

Unions and Intersections

Types are far more flexible when it comes to composition. You can create Union types (this OR that) which is something Interfaces cannot do directly.

type Status = "loading" | "success" | "error";
type RequestResult = SuccessResponse | ErrorResponse;

Extending and Implementing

Both can be extended, but the syntax differs. Interfaces use the extends keyword, which is familiar to those coming from Java or C#. Types use the intersection operator (&).

// Extending an Interface
interface Animal {
  name: string;
}

interface Dog extends Animal {
  breed: string;
}

// Intersecting a Type
type Person = {
  name: string;
};

type Employee = Person & {
  employeeId: number;
};

Performance and Error Messages

Historically, the TypeScript compiler was faster at checking interfaces than type intersections. While recent versions of TypeScript have minimized this gap, interfaces still generally provide better error messages when things go wrong, as they are named internal structures rather than computed aliases.

When to Use Which?

A good rule of thumb followed by many professional teams is:

1. Use Interfaces for public API definitions and when defining the shape of objects or classes. They are more extensible and follow standard OOP principles.
2. Use Types when you need to define unions, tuples, or aliases for primitive types. They are your tool for complex logic and data manipulation.

Advanced Pattern: The Hybrid Approach

In modern TypeScript applications, you will often see both used together. For example, you might use an Interface to define a Component's props but use a Type to define the specific 'Theme' or 'Variant' those props can accept.

type ButtonVariant = "primary" | "secondary" | "outline";

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant: ButtonVariant;
}

Index Signatures: Objects With Unknown Keys

Sometimes you don't know every key an object will have ahead of time — a dictionary of translations keyed by locale code, or a lookup table keyed by ID. Both Interfaces and Types support index signatures for this:

interface StringDictionary {
  [key: string]: string;
}

type NumberDictionary = {
  [key: string]: number;
};

const translations: StringDictionary = {
  en: "Hello",
  tr: "Merhaba",
};

An index signature says "every property on this object, regardless of its exact name, has this value type." This is different from the earlier Status union, which enumerates a fixed, known set of values — reach for an index signature when the set of keys is open-ended, and a union when the set of values is closed.

readonly: Preventing Accidental Mutation

Both constructs support marking individual properties readonly, which the compiler enforces at the type level (though, like all TypeScript checks, not at runtime):

interface Config {
  readonly apiUrl: string;
  timeout: number;
}

const config: Config = { apiUrl: "https://api.example.com", timeout: 5000 };
config.apiUrl = "https://evil.example.com"; // Error: Cannot assign to 'apiUrl' because it is a read-only property.
config.timeout = 3000; // fine — not marked readonly

This is a cheap way to document (and enforce, at compile time) that certain fields — an ID, a creation timestamp, a base URL — should never be reassigned after an object is constructed, without reaching for a full immutability library.

Mapped Types: Deriving New Types From Old Ones

Beyond Partial and Pick (TypeScript's built-in utility types), you can write your own mapped types that transform every property of an existing type according to a rule:

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

type ReadonlyUser = {
  readonly [K in keyof User]: User[K];
};

type OptionalUser = {
  [K in keyof User]?: User[K];
};

keyof User produces the union of User's key names ("id" | "username" | "email"), and [K in keyof User] iterates over that union to build a new type, one property at a time. This is genuinely the mechanism Partial<T> and Readonly<T> are built from internally — once you can read a mapped type like this, the built-in utility types stop feeling like magic and start feeling like a specific, readable pattern.

A Worked Example: Modeling an API Response

Here's how Types and Interfaces typically combine on a real feature — fetching a user profile from an API that might fail:

// Types for the closed set of possible request states
type RequestState = "idle" | "loading" | "success" | "error";

// Interface for the object shape returned on success
interface UserProfile {
  id: string;
  username: string;
  email: string;
}

// Type composing the interface into a union of possible results
type ProfileResult =
  | { state: "success"; data: UserProfile }
  | { state: "error"; message: string }
  | { state: "loading" | "idle" };

function renderProfile(result: ProfileResult) {
  if (result.state === "success") {
    console.log(result.data.username); // narrowed: TypeScript knows `data` exists here
  } else if (result.state === "error") {
    console.log(result.message); // narrowed: TypeScript knows `message` exists here
  }
}

This pattern — a discriminated union, where a shared field like state tells TypeScript which shape it's looking at — is one of the most useful things Types make possible that Interfaces alone cannot express directly. It replaces a pile of optional fields and manual undefined checks with a structure the compiler actively verifies for you.

Common Pitfalls

• Trying to union two Interfaces directly. interface A | interface B is not valid syntax — Interfaces can only be extended, not unioned. If you need a union, define it as a type composed of the interfaces: type Combined = A | B.
• Forgetting that declaration merging still applies within the same scope. Merging two same-named interfaces in the same module file (or in ambient/global declarations, like a declare global block or a non-module .d.ts file) is powerful for extending third-party types, but it also means an accidental duplicate interface name in one of those same scopes silently merges instead of erroring — which can produce a confusing shape you didn't intend. Ordinary same-named interfaces in two separate ES modules do not merge with each other; each module has its own scope.
• Assuming readonly protects nested objects. Just like Object.freeze() in plain JavaScript, readonly on a property only prevents reassigning that property — if the property's value is itself an object, its nested fields remain fully mutable unless you mark those readonly too.

Summary

Choosing between Types and Interfaces isn't always about which one is 'better,' but which one is 'fitter' for the current task. Interfaces excel at describing objects and staying open for extension via declaration merging, while Types excel at flexibility — unions, discriminated unions, and mapped types — for handling complex logic that Interfaces alone cannot express.

By mastering both, you ensure that your TypeScript codebase remains robust, readable, and easy to maintain as it grows.