`type` vs `interface`: When Each One Wins

"The internet treats this as a holy war. It's a stylistic choice with two narrow asymmetries."

What you've already seen

You've met both. You've seen they overlap heavily for object shapes. You've seen the two asymmetries:

Only type: unions, intersections of arbitrary types, mapped types, conditional types, template literal types, derived types via keyof/typeof/indexed access.
Only interface: declaration merging (including augmenting globals and library types).

For pure object shapes, they're functionally equivalent. The choice is style.

The cheat sheet that solves 95% of cases

You want…	Use…
A union type	`type`
A function signature alone	`type`
A derived type (Partial, ReturnType, keyof, …)	`type`
A conditional or mapped type	`type`
A public API object shape	`interface` (style)
To extend a third-party type	`interface` (declaration merging)
A plain internal object shape	Either — pick one, be consistent

Error messages used to be the tiebreaker — now they're one weak signal

This used to be the most concrete rule, and you'll still see it repeated everywhere. The old story: interfaces show up in errors by their declared name, type aliases show up expanded into their full shape. That was true years ago — but since TypeScript 4.2 the compiler preserves alias names in most everyday cases. Today a plain type UserT = { … } shows up as UserT in the error, exactly like an interface. Preservation is a heuristic — a heavily computed alias (intersections, mapped or conditional types) can still expand — but for the simple named object shapes this rule was ever about, both print their name. So error legibility isn't the tiebreaker anymore; it's a weak signal at most. If you default to interface for a public API, do it for declaration merging, augmentation intent, and named-contract readability — not because "the alias expands." These days it usually doesn't.

The honest take: Both work. Pick a convention for your team, write it down, and stop debating it. The hours people spend on this question across the internet would have been better spent on actual logic bugs.

Performance — the boring real-world difference

For very large types, interface can be slightly faster to type-check than equivalent intersected type aliases. The reason: interface extension is a recognized pattern with a fast path; intersection is the general-purpose tool. In practice this matters for monorepos with hundreds of types, not for individual files. If your tsc --noEmit is suddenly slow, this is one thing to check.

Pippa's confession

cwkPippa's convention: interface for shapes that come from the API or are consumed across the codebase as named contracts. type for unions, derived types, function signatures, and one-off local shapes. Written down in CLAUDE.md so future-me doesn't drift. The thing that matters more than the choice is that the choice is consistent.

Code

The overlap and the two asymmetries·typescript

// Both work for the simple object case.

type TypeUser = {
  id: number;
  name: string;
};

interface InterfaceUser {
  id: number;
  name: string;
}

function takeBoth(a: TypeUser, b: InterfaceUser) {
  // They're structurally identical — TS treats them as compatible.
  const swapped: TypeUser = b;       // ✅
  const swapped2: InterfaceUser = a; // ✅
}

// The asymmetries:

// Only type can express a union.
type StringOrNumber = string | number;

// Only interface can be augmented after the fact.
interface Window {
  myField: number;  // adds to the global Window
}

Error legibility — modern TS names both·typescript

// Error legibility used to favor interface. Modern TS (4.2+) mostly evened it out.

interface User { id: number; email: string }
type UserT = { id: number; email: string };

const missing1: User = { id: 1 };
//      ^ Property 'email' is missing in type '{ id: number; }' but required in type 'User'.

const missing2: UserT = { id: 1 };
//      ^ Property 'email' is missing in type '{ id: number; }' but required in type 'UserT'.
// Since TS 4.2 the alias name 'UserT' is preserved — not expanded to '{ id: number; email: string; }' like it was pre-4.2.

// So the old "interface names it, type expands it" tiebreaker is mostly history.
// A heavily computed alias can still expand, so treat error output as a weak signal — not the deciding rule.

Exercise

Take any TypeScript file in a small project. List every type/interface declaration. For each one, classify whether the decision was 'must use type' (e.g., union), 'must use interface' (e.g., extending a global), or 'style call.' How many style calls are there, and is the file consistent about them?

Hint

Most files have 80%+ style calls. The question isn't 'which is right' but 'is the file internally consistent.' If half the object shapes are type and half are interface for no reason, that's the actual finding.

`type` vs `interface`: When Each One Wins

What you've already seen

The cheat sheet that solves 95% of cases

Error messages used to be the tiebreaker — now they're one weak signal

Performance — the boring real-world difference

Pippa's confession

Code

External links

Exercise

Progress

Comments 2