Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 96 ยท Objects and Classes

Type Aliases vs Interfaces

Compare TypeScript type aliases and interfaces - what each can express, declaration merging, extends vs intersections, error messages, performance and a simple rule of thumb.

Sooner or later every TypeScript developer asks the same question: should this object type be a type or an interface? Both can describe an object, both can be implemented by a class, and for most everyday code the two are interchangeable. That is why the question causes so much debate, and why the honest answer is "it rarely matters, but here are the cases where it does."

This lesson puts the two side by side. You will see what they share, what only one of them can do, how declaration merging works, how extends differs from &, and how the choice affects error messages and compiler speed. It builds on Type Aliases and Interfaces, so read those first if the syntax is new.

What they have in common

For describing the shape of an object, the two forms are nearly identical. Both support optional and readonly members, method signatures, call signatures and index signatures. Both can be generic. Both can be used wherever a type is expected, and a class can implements either one.

TypeScript The same shape, two spellings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

The three lines print point at (1, 2), point at (1, 2) and start at (10, 20). Because TypeScript uses structural typing, PointI and PointT are the same type as far as assignability goes. The choice never changes which values are accepted, only how you write and extend the type.

What only a type alias can do

An interface can only describe an object-like shape (including functions and classes that are called or constructed). A type alias can name any type:

TypeScript
type Id = string | number;                    // a union
type Pair = [first: string, second: number];  // a tuple
type Meters = number;                         // a primitive
type Handler = (event: string) => void;       // a function type
type Keys = keyof { a: 1; b: 2 };             // the result of a type operator
type Nullable<T> = T | null;                  // a generic union
type Getters<T> = { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] };

Every row above is impossible with interface. In particular, unions, mapped types, conditional types and template literal types all need a type. If a model is "one of several shapes" (a discriminated union), that is a type too:

TypeScript
type Shape =
  | { kind: 'circle'; radius: number }
  | { kind: 'square'; size: number };

You can still use interfaces for the members of that union. The union itself has to be an alias.

What only an interface can do

The list in the other direction is short, but important.

Declaration merging

If you declare the same interface name twice in the same scope, TypeScript merges the declarations into one interface. A type alias with a repeated name is an error (TS2300, "Duplicate identifier").

TypeScript Declaration merging

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Both declarations of AppSettings contribute members, so the object literal must have both, and the program prints the merged object, then b and undefined. Because the file is a module, the declare global block is how you reach the global Array interface. The same mechanism lets you extend types from libraries: add your own property to Express's Request, to Window, or to the ProcessEnv type. This is called module augmentation or global augmentation, and it only works because those types are interfaces. It is the strongest reason to prefer interface for the types that library authors publish and that users may need to extend. Declaration Files shows the pattern in more depth.

Declaration merging is also a footgun. Two unrelated files can accidentally merge two interfaces that happen to share a name, silently changing a type. With a type alias you get an error instead of a surprise.

What a class can implement

A class can implements a type alias if the alias is an object type, but you cannot implements a union alias (TS2422, "A class can only implement an object type or intersection of object types with statically known members"). An interface is always a valid target.

Extending: extends versus &

Both forms let you build a bigger shape out of smaller ones:

TypeScript
interface Animal { name: string }
interface Dog extends Animal { barks: boolean }

type AnimalT = { name: string };
type DogT = AnimalT & { barks: boolean };

They look equivalent, and for compatible members they are. The difference shows up when the two sides disagree about a property:

  • With interface Dog extends Animal, TypeScript checks the child against the parent when it sees the declaration. If a property is incompatible, you get an error at the declaration (TS2430, "Interface 'Dog' incorrectly extends interface 'Animal'").
  • With an intersection A & B, TypeScript does not complain. It combines the property types with &. If they cannot overlap, for example string & number, the property quietly becomes never, and the error only appears later, far away, when you try to use the value.
TypeScript Conflicting property: error now or never later

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

So interfaces catch accidental conflicts earlier and name them better. Intersections are more flexible, because they work with unions and other non-interface types. You can also use extends on an interface to extend a type alias that has an object type, as in interface Dog extends AnimalT { barks: boolean }.

flowchart TD
    A["Need to name a type"] --> B{"Is it an object shape?"}
    B -- "No: union, tuple, primitive,<br/>function, mapped, conditional" --> T["Use type"]
    B -- Yes --> C{"Will others extend or<br/>augment it, or will you<br/>rely on merging?"}
    C -- Yes --> I["Use interface"]
    C -- No --> D{"Does your team have<br/>a convention?"}
    D -- Yes --> E["Follow it"]
    D -- No --> F["Either works: pick one<br/>and stay consistent"]

A practical way to decide between type and interface.

Error messages and hover text

Interfaces keep their name in the editor and in error messages. A type alias for an object usually does too, but intersections and complex aliases are often expanded into their parts, which can make a message long and hard to read:

TypeScript
type A = { a: string };
type B = { b: number };
type C = { c: boolean };
type All = A & B & C;
// An error about All may print: Type '{ a: string; }' is missing the following
// properties from type 'A & B & C': b, c

With interface All extends A, B, C {} the message just says "Interface 'All'". For public API types that people will read in tooltips every day, a named interface is a small kindness. For internal types the difference rarely matters.

Performance

You will sometimes read that interfaces are faster than type aliases. There is a real effect behind that claim, but it is small and only matters in big codebases.

When TypeScript checks interface B extends A, it creates one object type with a base type and caches the relationship. An intersection of object types is re-evaluated each time and must be flattened, which costs more when you intersect many large types again and again. The TypeScript team's guidance is to prefer interfaces with extends over intersections of object types when both would work, and to use named types instead of repeating large inline types.

Do not rewrite a working project for this. Measure first (with tsc --extendedDiagnostics) if your build is slow, and look for the real culprits, which are usually deeply recursive conditional types and huge unions, not the keyword you used for a plain object.

A simple rule of thumb

Here is a rule that works for most teams:

  1. Anything that is not an object shape (unions, tuples, function types, mapped and conditional types, primitives) is a type. You have no choice.
  2. Object shapes that are part of a public, extensible API (a library's options, a plugin interface, something a user might augment) are an interface.
  3. Everything else (props, DTOs, internal data) can be either. Pick one default for the whole project, write it down, and stay consistent.

Many style guides, and many linters (the @typescript-eslint/consistent-type-definitions rule), simply pick one: either "always interface for objects" or "always type". Both are fine. What is not fine is mixing them at random inside the same module, because the reader then wonders whether the difference is meaningful.

If a reviewer asks "why type here?" the best answers are "it is a union" or "it uses a mapped type". If they ask "why interface?" the best answer is "consumers may need to extend it".

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which of these can be written ONLY with a type alias?

    Interfaces describe object shapes. Unions, tuples, primitives and mapped or conditional types need a type alias.
  2. 2. What happens if you declare interface Config twice in the same scope with different members?

    Interfaces merge. A type alias declared twice is an error, which makes aliases safer against accidental merging.
  3. 3. interface Dog extends Animal and type Dog = Animal & {...} disagree about the type of id. What do you see?

    An interface is checked against its parent when declared. An intersection just combines the property types, which can reduce to never.
  4. 4. A library author wants users to add their own fields to an options type. Which is the better choice?

    Only interfaces support declaration merging, which is how module augmentation works.
  5. 5. Does choosing interface over type change which values are assignable to an object type?

    Assignability is structural for both. The choice affects extension, merging, messages and compiler caching, not which values fit.

Summary

  • For plain object shapes, type and interface are interchangeable, and values flow freely between them because TypeScript compares structure.
  • Only a type can name unions, tuples, primitives, function types, mapped, conditional and template literal types.
  • Only an interface supports declaration merging, which is how libraries let you augment their types.
  • interface extends reports conflicting members at the declaration; an intersection (&) quietly produces never for conflicting properties.
  • Interfaces usually give shorter names in errors and are slightly cheaper for the compiler than large intersections, but this rarely matters in practice.
  • Use type when you must, interface for extensible public object shapes, and one agreed default for the rest.

Next: Generics