TypeScript Interface vs Type: Real Differences, Tested With the Compiler

Few TypeScript questions cause as much debate as TypeScript interface vs type. Many articles list differences that used to matter in older versions but are now out of date. So rather than repeating claims, we tested them.

We wrote one file exercising each difference, and checked it with TypeScript 5.6.3 in strict mode. The compiler errors quoted below come from that run. Behaviour can change between versions, so check against the TypeScript version your project uses. If you are new to the language, start with our TypeScript tutorial for beginners.

The short answer

An interface describes the shape of an object, and can be extended or reopened. A type alias gives a name to any type, including objects, unions, tuples and function types. Where both can work, the difference is mostly style.

Where they are the same

These two declarations describe identical shapes:

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

type UserAlias = {
  id: number;
  name: string;
  email?: string;
};

const a: User = { id: 1, name: "Asha" };
const b: UserAlias = a;   // no error

TypeScript uses structural typing, which means it compares shapes rather than names. That is why a User can be assigned to a UserAlias with no complaint. Both support optional properties, readonly properties, methods and index signatures.

Interface vs type side by side

What only type can do

Many useful types are not object shapes at all, and only a type alias can name them:

type Status = "pending" | "paid" | "shipped";   // union
type Point = [number, number];                    // tuple
type Handler = (event: string) => void;           // function type
type Keys = keyof User;                           // computed type
type ReadonlyUser = Readonly<User>;               // utility type

Union types are among TypeScript’s most valuable features, because the compiler then rejects any value outside the list:

let s: Status = "paid";
s = "refunded";

// error TS2322: Type '"refunded"' is not assignable to type 'Status'.

This catches typos and outdated values at compile time, before they reach production.

Declaration merging

If you declare an interface with the same name twice, TypeScript merges them into one:

interface Settings {
  theme: string;
}
interface Settings {
  language: string;
}

const settings: Settings = { theme: "dark", language: "en" };   // no error

Try the same thing with a type alias, and the compiler refuses:

type Config = { theme: string };
type Config = { language: string };

// error TS2300: Duplicate identifier 'Config'.

Merging is how libraries let you extend their types. For example, you can add a custom property to the global Window interface, or to a framework’s request object, without modifying the library. That is genuinely useful.

The flip side is that merging can happen by accident. If two files in a project declare an interface with the same name in the same scope, they silently combine, which can be confusing. A type alias makes that collision an error instead.

extends vs intersections

Both let you build on an existing type:

interface Admin extends User {
  permissions: string[];
}

type AdminAlias = UserAlias & { permissions: string[] };

For compatible properties, the result is the same. The difference shows up with a conflict. When an interface tries to change a property’s type incompatibly, the compiler reports it at once:

interface Base { id: number }
interface Broken extends Base { id: string }

// error TS2430: Interface 'Broken' incorrectly extends interface 'Base'.
//   Types of property 'id' are incompatible.
//     Type 'string' is not assignable to type 'number'.

An intersection does not complain when it is declared. Instead, the conflicting property becomes never, a type that no value can have. The error only appears later, when you try to use it:

type Mixed = { id: number } & { id: string };
const m: Mixed = { id: 1 };

// error TS2322: Type 'number' is not assignable to type 'never'.

That later error is more confusing, since it points away from the actual mistake. This is one practical reason to prefer extends when building up object types.

Classes and implements

A class can promise to match a shape using implements, and this works with an interface or an object type alias:

class Account implements User {
  constructor(public id: number, public name: string) {}
}

This compiled without errors. Note that implements only checks that the class matches. It does not add any properties or code. A class cannot implement a union type, since there is no single shape to match.

Readonly and utility types

Utility types such as Readonly, Partial, Pick and Omit work with both interfaces and aliases. The result is a new type, which is typically named with a type alias:

const r: ReadonlyUser = { id: 3, name: "Dev" };
r.name = "Chitra";

// error TS2540: Cannot assign to 'name' because it is a read-only property.

Remember that readonly is a compile-time check only. At run time the object is ordinary JavaScript, and it can still be changed by code that bypasses the types.

Compiler performance

The TypeScript team’s own performance guidance suggests preferring interfaces that use extends over large intersections, because the compiler can cache interface relationships more efficiently. In small and medium projects you are unlikely to notice any difference. It may matter in very large codebases with deeply composed types. We did not measure this ourselves.

Which should you use?

A widely used rule, in line with guidance from the TypeScript handbook, is:

• Use interface for object shapes, especially public APIs and anything that classes implement or others may extend.
• Use type for unions, tuples, function types, and mapped or computed types.

Some teams simply use type everywhere, and that also works well. What matters most is consistency, so pick a convention, write it in your style guide and let a linter enforce it. ESLint’s consistent-type-definitions rule from typescript-eslint can do this.

Common mistakes

• Endless debate. Both are fine for objects, so settle the rule once and move on.
• Accidental merging. Reusing an interface name in the same scope silently combines them.
• Conflicting intersections. They create never types with confusing errors later.
• Trusting types at run time. They are erased, so validate external data.
• Using any to silence errors. It switches off checking. Prefer unknown and narrow it.

Switching between them in an existing codebase

Changing an interface to a type, or the reverse, is usually safe for plain object shapes, because TypeScript compares types by their structure, not by their names. A few things still need checking before you switch:

• Converting an interface to a type alias removes declaration merging, so any second declaration with the same name becomes a duplicate identifier error.
• Converting a type alias to an interface only works for object shapes. Unions, tuples and mapped types must stay as type aliases.
• Error messages and editor hovers may display the type differently, which can surprise teammates but does not change behaviour.

Make the change in one focused pull request, run the compiler in strict mode and your test suite, and avoid mixing it with feature work so reviewers can see that nothing else changed.

Final thoughts

The interface vs type question has a calm answer: they overlap for objects, each has a few unique abilities, and consistency matters more than the choice. Use interfaces for shapes and types for everything else, unless your team prefers otherwise. To see the differences yourself, copy the examples above into a file and run tsc --noEmit --strict on it.

Frequently asked questions

Keep learning