Type Aliases vs Interfaces in TypeScript: The Real Difference

This is the single most-asked TypeScript question after “what’s any vs unknown,” and most answers you’ll find are outdated, overly dogmatic, or just wrong about what actually differs. The honest answer: for describing plain object shapes, type and interface are close enough to interchangeable that team convention matters more than technical necessity. But they are not identical, and the differences that do exist have real consequences once your codebase grows or starts consuming third-party libraries.

Where They Look Identical

interface UserInterface {
  name: string;
  age: number;
}

type UserType = {
  name: string;
  age: number;
};

function greetInterface(user: UserInterface) { return `Hi ${user.name}`; }
function greetType(user: UserType) { return `Hi ${user.name}`; }

greetInterface({ name: "Alice", age: 30 });   // works
greetType({ name: "Alice", age: 30 });          // works — identical shape, identical behavior

For this exact case — a plain object shape — the compiled output is identical (both erase completely), the structural typing rules apply identically, and either one type-checks the same calling code the same way. If your team has no strong convention, this case genuinely doesn’t matter. The differences show up at the edges.

Difference 1: type Can Alias Anything; interface Only Describes Object Shapes

type ID = string | number;                          // union — interface cannot do this
type Coordinates = [number, number];                  // tuple — interface cannot do this
type Handler = (event: Event) => void;                // function type — interface CAN do this, awkwardly
type Nullable<T> = T | null;                          // generic alias over any type — interface cannot do this

// This is NOT possible with interface:
// interface ID = string | number;   ← syntax error, interfaces can't alias a union

type is a general-purpose naming mechanism — it can alias a union, an intersection, a tuple, a primitive, a mapped type, or an object shape. interface is specifically for describing the shape of an object (or a callable, as covered in the interfaces guide) — it has no syntax for aliasing a union or a primitive at all. This alone settles a large share of the “which one” question: if what you’re naming isn’t a plain object shape, type is your only option.

Difference 2: Declaration Merging

interface Config {
  apiUrl: string;
}

interface Config {
  timeout: number;
}

// Merged automatically — Config now requires BOTH apiUrl and timeout
const config: Config = { apiUrl: "https://api.example.com", timeout: 5000 };

type ConfigType = {
  apiUrl: string;
};

type ConfigType = {
  timeout: number;
};
// Error: Duplicate identifier 'ConfigType'

Declaring an interface twice with the same name merges the two declarations into one combined shape (covered in depth in the interfaces guide); declaring a type alias twice with the same name is a hard compile error. This is the sharpest, least negotiable difference between the two — and it’s exactly why library type definitions (like Express’s Request, or the global Window object) are almost always written as interface, not type: it’s the only one of the two that lets consumers extend the shape from their own code without modifying the original declaration.

Difference 3: Intersections vs Extends

// interface: extends
interface Animal {
  name: string;
}
interface Dog extends Animal {
  breed: string;
}

// type: intersection (&)
type AnimalType = {
  name: string;
};
type DogType = AnimalType & {
  breed: string;
};

These look nearly equivalent, and for straightforward cases they behave the same. The difference emerges with conflicting property types: interface extends errors immediately if the extending interface redeclares an inherited property with an incompatible type, while a type intersection silently collapses conflicting types down to never for that property, deferring the error until you actually try to use it.

interface A { prop: string; }
interface B extends A { prop: number; }
// Error immediately: Interface 'B' incorrectly extends interface 'A' — types of property 'prop' are incompatible

type AT = { prop: string };
type BT = AT & { prop: number };
// No error here! BT.prop's type silently becomes `never`
// (string & number has no valid values — the error only surfaces later, when you try to assign to prop)

This is a real, cited reason some style guides prefer interface for object shapes specifically: a conflicting property type is caught immediately at the point of declaration, rather than silently producing an unusable never type that only fails later, at a point further from the actual mistake.

Difference 4: Readability for Complex Unions

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number }
  | { kind: "rectangle"; width: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle": return Math.PI * shape.radius ** 2;
    case "square": return shape.side ** 2;
    case "rectangle": return shape.width * shape.height;
  }
}

Discriminated unions like this — one of the most useful patterns in the entire type system — are only expressible as type. There’s no interface syntax for “one of these three distinct shapes.” Any time the shape you’re modeling is genuinely “this OR that,” not “always these properties,” type is the only tool that fits.

Performance: Does It Actually Matter?

TypeScript’s own team has noted that, for large, deeply-nested structural type checks, interface can type-check marginally faster than an equivalent type intersection, because interfaces are cached and compared by declaration identity in some cases, while intersections must be recomputed more often. In practice, this difference is measurable only in very large codebases with pathologically complex type compositions — it should never be the deciding factor for an application of normal size, and no team should choose interface over type purely for this reason without profiling an actual compile-time problem first.

A Practical Rule of Thumb

Some teams enforce this consistently with an ESLint rule:

{
  "rules": {
    "@typescript-eslint/consistent-type-definitions": ["error", "interface"]
  }
}

This flags any plain object shape declared with type instead of interface (unions, intersections, and other non-object-shape types are unaffected by the rule), which removes the “which one did we use last time” bikeshedding from code review entirely — the linter enforces the convention instead of a human needing to remember it.

Many teams adopt a simple default — “use interface for object shapes, type for everything else (unions, tuples, function types, generics)” — and that single rule resolves the overwhelming majority of real cases without needing to memorize every edge-case difference above.

Generics Work on Both

interface Box<T> {
  value: T;
}

type BoxType<T> = {
  value: T;
};

const stringBox: Box<string> = { value: "hello" };
const numberBox: BoxType<number> = { value: 42 };

Both support generic type parameters with identical syntax and identical behavior for plain object shapes — this isn’t a differentiator between them. Where it does diverge is in more advanced generic constructs: conditional types, mapped types, and infer (covered in the mapped and conditional types guide) can only be expressed with type — there’s no interface syntax for a conditional type at all.

Recursive Types

// Both interface and type support self-reference for object shapes
interface TreeNode {
  value: number;
  children: TreeNode[];
}

type JSONValue =
  | string
  | number
  | boolean
  | null
  | JSONValue[]
  | { [key: string]: JSONValue };

Interfaces have always supported recursive self-reference naturally, since an interface’s properties can reference the interface’s own name directly. type aliases gained robust support for recursive references (like the JSONValue example, which models literally any valid JSON value) more recently in the language’s history — for a genuinely recursive union like this, type is the only option anyway, since unions aren’t expressible as interface at all.

What Neither One Does

Neither type nor interface produces anything at runtime — both are compile-time-only constructs, fully erased before your code runs (see how TypeScript works for why). This means neither can be used with instanceof, neither shows up if you console.log an object’s constructor, and neither adds a single byte to your compiled JavaScript output regardless of how large or deeply nested the type definition is.

interface User { name: string; }
type UserT = { name: string; };

const obj = { name: "Alice" };
console.log(obj instanceof User);    // compile error — User has no runtime existence to check against

Frequently Asked Questions

If I’m not sure, which should I default to? interface for anything describing an object’s shape, type for anything else. This single heuristic handles the vast majority of real decisions without requiring the deeper edge cases in this guide.

Can I convert an interface to a type (or back) without breaking anything? For plain object shapes with no re-declaration/merging happening elsewhere in the codebase, usually yes — but search first for any other declaration of the same interface name (declaration merging is easy to miss when it’s spread across multiple files, which is common in larger codebases and library type definitions).

Does using type instead of interface change my compiled JavaScript output? No — never. Both are completely erased at compile time regardless of which one you choose; the entire difference lives in what the compiler checks before your code runs, not in what runs.

Why do library .d.ts files almost always use interface for exported object types? Because declaration merging lets consumers of the library extend those types from their own code (adding a custom property to Request, for instance) without needing the library itself to anticipate every possible extension. A type alias can’t be augmented this way at all — that’s a real, load-bearing reason, not just convention.

Is there a case where mixing type and interface for the same conceptual shape causes real problems? Yes — a type alias for a union or intersection generally cannot be used with extends-style narrowing the way an interface hierarchy can, and an interface extending a type alias that resolves to a union will produce confusing errors. Keep one shape’s entire declaration in one form rather than mixing type and interface for the same evolving concept.

Will this decision ever need revisiting as a codebase grows? Rarely for the object-shape case, since both erase identically and neither imposes a runtime or bundle-size cost. The one scenario worth watching for: a shape that started as a simple object and later needs to become a discriminated union (adding a kind field with variants) — at that point, an interface has to be converted to type anyway, since unions aren’t expressible as interface. Anticipating that possibility is a reasonable, if minor, argument for defaulting new object shapes to type in codebases that expect a lot of evolving domain modeling.

What’s Next

You now have a concrete, edge-case-aware answer to a question most resources leave vague. Next: Union and Intersection Types, where we go deeper into the | and & operators that type aliases unlock — including the discriminated union pattern briefly shown above, which is one of the most practically useful tools in the entire type system.