type vs interface in TypeScript - What You Really Need to Know

You've definitely come across this debate more than once: type or interface? Most answers online boil down to "it depends" or "use interface for objects, type for everything else." That's not wrong, but it's incomplete. This article breaks the topic down properly.

---

What is type, what is interface

interface is a contract describing the shape of an object. It's been in TypeScript from the beginning and for years was the way to describe data structures. Semantically it says: "every value of this type must look like this."

type is an alias (you give a name to any type expression). That can be an object, a union, an intersection, a primitive, a tuple, a function, anything.

The core mental distinction: interface defines a shape. type names any type expression.

---

Where they're identical

Before getting to the differences, let's be clear about what is not a difference, because the internet is full of myths here.

Describing object shapes

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

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

Identical result. Neither is "better" for describing objects.

Generics

interface Box<T> {
  value: T;
}

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

Both support generics. No difference here.

Extension

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

// type & type
type Animal = { name: string };
type Dog = Animal & { breed: string };

// interface extends type (yes, this works)
type Animal = { name: string };
interface Dog extends Animal {
  breed: string;
}

// type & interface (this works too)
interface Animal {
  name: string;
}
type Dog = Animal & { breed: string };

All four variants compile without issues. extends and & are practically equivalent in most cases, with one exception covered below.

---

Where they difference

1. Unions - type only

type Status = "active" | "inactive" | "pending"; // ✅

interface Status = "active" | "inactive" | "pending"; // ❌ syntax error

interface cannot describe a union. Its syntax requires curly braces and a list of properties. If you need a union, then you have to use type.

Same goes for conditional types, mapped types, and tuple types:

type MaybeString = string | null;
type Readonly<T> = { readonly [K in keyof T]: T[K] };
type Pair = [string, number];

None of the above can be expressed with interface.

2. Declaration merging - interface only

This is the difference that has real practical consequences.

An interface with the same name declared in two places does not cause an error, it merges:

interface Config {
  timeout: number;
}

interface Config {
  retries: number;
}

// Result: Config = { timeout: number; retries: number }
const c: Config = {
  timeout: 3000,
  retries: 3,
};

With type, this is a compile error:

type Config = { timeout: number };
type Config = { retries: number }; // ❌ Duplicate identifier 'Config'

Type conflict during merging

What if both interfaces declare the same field with conflicting types?

interface A {
  x: number;
}

interface A {
  x: string; // ❌ error - conflict during merging
}

The compiler reports the error at the declaration site, not at the point of use. The merge attempts to combine number and string on field x which is impossible.

---

3. extends vs & - difference in error reporting

Technically you get the same result, but the compiler behaves differently when something goes wrong.

interface A {
  x: number;
}

interface B extends A {
  x: string; // ❌ immediate error: "Interface 'B' incorrectly extends interface 'A'"
}

type A = { x: number };
type B = A & { x: string };
// No error at declaration!
// But B.x has type: never

With &, the compiler won't complain at the definition, you'll get never on field x, which only surfaces when you try to use it. This is a subtle trap: never instead of an error can slip through code review unnoticed.

---

When declaration merging is actually needed

There are two specific, intentional use cases of declaration merging.

Augmenting global objects

You want to add a field to the built-in Window:

// globals.d.ts

declare global {
  interface Window {
    analytics: Analytics;
  }
}

Why doesn't type work here?

type Window = { analytics: Analytics }; // ❌

This creates a new type named Window that conflicts with the built-in Window. You're trying to overwrite, instead of extending the original.

interface uses declaration merging. Your declaration gets merged into the existing one. The original Window still exists, analytics is added onto it.

Augmenting types from external libraries

A library exports an interface you want to extend without touching node_modules:

// types/tailwindcss-vite.d.ts

import "@tailwindcss/vite";

declare module "@tailwindcss/vite" {
  interface Theme {
    borderRadius: number;
  }
}

The mechanism: declare module tells the compiler "this is an augmentation of an existing module." Inside, you use declaration merging on interface Theme adding a field to what the library already exports.

Note: you import the module (import "@tailwindcss/vite") before augmenting it. Without this, the compiler doesn't know what to look for.

Using type instead of interface here won't work. type is not subject to augmentation.

---

Summary

There's no single rule every dev follows, but there are solid heuristics:

Use type when:

• you need unions, intersections, tuples, mapped types, or conditional types
• you're describing data (API response, payload, DTO), things that shouldn't be extended by external code
• you want a duplicate name to fail fast with a compiler error

Use interface when:

• you're deliberately using declaration merging (augmenting globals, extending library types)
• you're writing a library and want to give consumers the ability to extend your types via augmentation