Types versus interfaces in 2024, which one should you use?

This is the million dollar question. I think that, after “do I have to know JavaScript to learn TypeScript”, this is the question I’ve gotten the most so far: “When do I use interfaces and when do I use types?”

And I’ll go even further. Why do interfaces exist at all if types already do everything they do?

To understand all of this we need to understand what a type is, what an interface is, and what the difference between the two actually is.

Types#

Types are TypeScript’s building blocks, it’s even in the name. They’re the most important and basic things we have in the language.

A type can represent any other type in TypeScript, not just simple, primitive types, but objects too.

So we can do simple things like:

1
type str = string
2
type n = number

As well as:

1
type pessoa = {
2
  nome: string
3
}
4
type filter = (predicate: string) => string

In other words, types can represent any object and any interface in TypeScript.

Interfaces#

Interfaces come from an object-oriented approach, as opposed to the more functional approach of types. They’ve existed since the very first version of TypeScript and were created to make design patterns that require polymorphism possible.

Unlike types, interfaces can only represent objects, they can’t represent simple or primitive types.

1
interface pessoa {
2
  nome: string
3
}

Differences between types and interfaces#

When we’re dealing with two tools that look this similar, it’s hard to know when to use one and when to use the other. Before we get to that, I want to dedicate this section specifically to the differences between types and interfaces.

Interfaces can’t express mapped types#

Unlike types, interfaces can’t express mapped types. For example, if we want a Partial<T> type, we can’t have an interface for it:

1
type partial<T> = {
2
  [K in keyof T]?: T[K]
3
}
4

5
interface Pessoa {
6
    nome: string
7
}
8

9
type partialPessoa = partial<Pessoa>

Types don’t express extensions efficiently#

As we saw before, types follow a more functional approach, unlike interfaces which follow a more object-oriented one.

That means when we have a type that extends another type, in other words it’s the union of those two types, we need to write it like this:

1
type idade = { idade: number }
2
type nome = { nome: string }
3
type pessoa = nome & idade // { nome: string, idade: number }

While we can express the same thing in interfaces using the extends keyword:

1
interface Nome {
2
  nome: string
3
}
4

5
interface Pessoa extends Nome {
6
  idade: number
7
}

I, personally, find interfaces easier to read in this case. But types have a problem when it comes to dealing with unions and intersections: they can’t be cached.

All the validation and all the type calculation happens in real time, done by the compiler, while interfaces can be cached because they can’t be changed dynamically, except through something called declaration merging which, coincidentally (or not), is our next topic.

Interfaces support declaration merging#

Declaration merging is also called “open type”. While interfaces are open types, every type alias is considered a closed type. For example, we can’t create two types with the same name:

1
type dog = string
2
type dog = number // error

A type can only exist in one single place, defined once, while interfaces can do what’s called declaration merging. In other words, if we declare an interface multiple times, the differences between the first declaration and the second get added to the same type:

1
interface Pessoa {
2
  nome: string
3
} // Pessoa is an object { nome: string }
4

5
interface Pessoa {
6
  idade: number
7
} // Pessoa is now { nome: string, idade: number }

While a lot of people consider this a problem (and use lint rules like ESLint’s no-redeclare), others think it’s fine. The truth is this feature isn’t just fine, it’s actually necessary for TS to work at all.

If you look at TS’s standard libraries, you’ll notice we have a bunch of interfaces that get redeclared. For example, in lib.es2015.promise.d.ts, we have the declaration of what a promise is as a constructor, and then in lib.es5.d.ts we have the declaration of the promise itself:

1
interface Promise<T> {
2
    /**
3
     * Attaches callbacks for the resolution and/or rejection of the Promise.
4
     * @param onfulfilled The callback to execute when the Promise is resolved.
5
     * @param onrejected The callback to execute when the Promise is rejected.
6
     * @returns A Promise for the completion of which ever callback is executed.
7
     */
8
    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
9

10
    /**
11
     * Attaches a callback for only the rejection of the Promise.
12
     * @param onrejected The callback to execute when the Promise is rejected.
13
     * @returns A Promise for the completion of the callback.
14
     */
15
    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>;
16
}

Now, we have another standard library, lib.es2018.promise.d.ts, that redeclares the same interface I just showed you, but it adds finally to it:

1
interface Promise<T> {
2
    /**
3
     * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The
4
     * resolved value cannot be modified from the callback.
5
     * @param onfinally The callback to execute when the Promise is settled (fulfilled or rejected).
6
     * @returns A Promise for the completion of the callback.
7
     */
8
    finally(onfinally?: (() => void) | undefined | null): Promise<T>;
9
}

This matters because the TS team doesn’t need to keep giant files around. Every new ECMAScript version, people can create a new standard library with just the changes. Without declaration merging, TypeScript couldn’t sustain itself.

Index signatures work differently in types and interfaces#

When we create a type that’s an object, for example:

1
type Pessoa = {
2
  nome: string
3
  idade: number
4
}

We’ll be able to do something that, in my opinion, shouldn’t happen at all. We can attach an index signature straight to the type, even if it doesn’t have one:

1
type Pessoa = {
2
  nome: string
3
  idade: number
4
}
5

6
const Joao: Pessoa = {
7
  nome: 'João',
8
  idade: 32
9
}
10

11
type RecordGenerico = Record<string, number|string>
12
const meuRecord: RecordGenerico = Joao

So it’s as if our Pessoa type implicitly had this:

1
type Pessoa = {
2
  nome: string
3
  idade: number
4
  [x: string]: string|number
5
}

Meaning we can attach keys that belong to any of the types present in the type alias’s object.

In interfaces this isn’t allowed, and you have to explicitly say that the interface has an index signature, otherwise you’ll get an error:

1
interface Pessoa {
2
  nome: string
3
  idade: number
4
}
5

6
const Joao: Pessoa = {
7
  nome: 'João',
8
  idade: 32
9
}
10

11
type RecordGenerico = Record<string, number|string>
12
const meuRecord: RecordGenerico = Joao // error

But this works:

1
interface Pessoa {
2
  nome: string
3
  idade: number
4
  [x: string]: string|number
5
}
6

7
const Joao: Pessoa = {
8
  nome: 'João',
9
  idade: 32
10
}
11

12
type RecordGenerico = Record<string, number|string>
13
const meuRecord: RecordGenerico = Joao

When to use each one#

There’s no gain or loss from using only types or only interfaces, so it really comes down to whoever is using these features. Personally, I prefer the following structure:

If I’m defining a type that’s an object, then I use interfaces
For every other case, use types

Why?

Simply because interfaces were designed with the idea of modeling dynamic objects in JavaScript, and types weren’t. So when we use interfaces, TypeScript does a series of optimizations to make your compilation a bit faster.

Beyond that, interfaces can be extended in a more expressive way, and you can work with declaration merging (carefully) to express highly dynamic types, something that isn’t possible with types.

But types are very flexible, so it makes sense to use types in cases like:

Creating an alias to reduce the complexity of a more elaborate type
Expressing utility types
Creating generics that will be used as helpers

Using interfaces is a fairly personal choice. In general, my advice is to be consistent. So if you’re using interfaces for objects, don’t use types, and if you’re only using types, don’t use interfaces.

But you’ll find it’s pretty hard to avoid interfaces, especially if you’re following object-oriented patterns, because it’s a much more expressive way to implement classes, for example.