Types versus interfaces in 2024: which to use?

That’s the million-dollar question. I think that after “do I have to know JavaScript to learn TypeScript”, this has been the question I’ve received most often: “When should I use interfaces and when should I use types?”

And I’ll go further! Why do interfaces exist if types can do everything they can?

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

Types#

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

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

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

That is, types can represent any object and any interface in TypeScript.

Interfaces#

Interfaces come from an object-oriented approach, opposite to a more functional approach of types. They have existed since the first version of TypeScript and were created to enable design patterns that require polymorphism.

Unlike types, interfaces represent only objects, they cannot represent simple or primitive types.

1
interface pessoa {
2
  nome: string
3
}

Differences between types and interfaces#

When dealing with these two very similar tools, it’s hard to know when to use one and when to use the other. Before getting to that point, I want to use this section specifically to state the differences between types and interfaces.

Interfaces cannot express mapped types#

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

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 cannot express extensions efficiently#

As we saw earlier, types follow a more functional approach, unlike interfaces that follow a more object-oriented approach.

This means that when we have a type that extends another type, that is, it’s the union of these two types, we need to represent 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 this in interfaces using the extends keyword:

1
interface Nome {
2
  nome: string
3
}
4

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

Personally, I find interfaces simpler to read in this case. But types have a problem when we have to deal with unions and intersections: they cannot be cached.

All validation and all type calculations are done in real-time by the compiler, while interfaces can be cached because they cannot be changed dynamically, only through something called declaration merging, which, coincidentally (or not), is our next topic.

Interfaces support declaration merging#

Declaration merging is also called an “open type”. While interfaces are open types, all type aliases are considered closed types. For example, we cannot create two types with the same name:

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

A type can exist in only one place, only once, while interfaces can do what’s called declaration merging, that is, if we declare it multiple times, the differences between the first declaration and the second are 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 many people consider this a problem (and use lint rules like ESLint’s no-redeclare), others consider it okay. The truth is that this functionality is not just okay, but it’s necessary for TS to work.

If you look at the TS standard libraries, you’ll notice that we have a series of interfaces that are redeclared. For example, in lib.es2015.promise.d.ts, we have the declaration of what a promise is as a constructor, while 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, but it adds finally to the interface:

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 is important because the TS team doesn’t need to maintain huge files. With each new ECMAScript version, they can create a new standard library with only the changes. Without declaration merging, TypeScript couldn’t maintain itself.

Index signatures are different in types and interfaces#

When we create a type that is 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. Which is to assign an index signature directly 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 type Pessoa implicitly had this:

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

Meaning that we can assign keys that are part of any types present in the type alias object.

In interfaces, this is not allowed, and you must 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 // erro

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 in using only types or only interfaces, so the choice is up to whoever is using these features. Personally, I prefer the following structure:

If I’m defining a type that is an object, then I use interfaces
For all other cases, use types

Why?

Simply because interfaces were designed with the idea of modeling dynamic objects in JavaScript, and types were not. So when we use interfaces, TypeScript makes a series of optimizations to make your compilation a little faster.

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

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

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

The use of interfaces is quite personal. Overall, my advice is that you be consistent. So if you’re using interfaces for objects, don’t use types, and if you’re using only types, don’t use interfaces.

However, you’ll find that it’s quite hard not to use interfaces, especially if you’re following object-oriented principles, because it’s a much more expressive way to implement classes, for example.