Interface vs type em TypeScript: diferenças e quando usar

Para descrever o formato de um objeto, interface e type fazem o mesmo trabalho, e valores de um podem ser atribuídos ao outro quando os formatos coincidem. As diferenças estão nas bordas: o type pode nomear coisas que uma interface não pode (unions, tuplas, tipos calculados), e uma interface faz algumas coisas que um type alias não faz (merging, extends verificado).

interface PointI {
  x: number;
  y: number;
}

type PointT = {
  x: number;
  y: number;
};

const a: PointI = { x: 1, y: 2 };
const b: PointT = a; // same shape, so they are interchangeable
const c: PointI = b;

function show(p: PointI): string {
  return `(${p.x}, ${p.y})`;
}

console.log(show(b), show(c)); // (1, 2) (1, 2)

O TypeScript compara tipos de objeto pela estrutura, então o nome da declaração não importa para a compatibilidade. A seguir estão os lugares em que a escolha importa.

Tabela comparativa

O que só o type faz

Tudo o que não é um único formato de objeto precisa de um type alias:

type Status = "idle" | "loading" | "done";                   // union of literals
type Coordinates = [lat: number, lng: number];               // tuple
type Handler = (event: string) => void;                      // function type
type ID = string | number;                                   // union of primitives
type Flags<T> = { [K in keyof T]: boolean };                 // mapped type
type ElementOf<T> = T extends readonly (infer U)[] ? U : T;  // conditional type

const current: Status = "loading";
const here: Coordinates = [51.5, -0.12];
const onSave: Handler = (e) => console.log("saved:", e);
const flags: Flags<{ dark: string; beta: number }> = { dark: true, beta: false };
const first: ElementOf<string[]> = "a";

onSave(current);
console.log(here, flags, first);
// saved: loading
// [ 51.5, -0.12 ] { dark: true, beta: false } a

Nada disso pode ser escrito com interface (os dois últimos são tratados em mapped types e conditional types). Esse é o motivo prático de toda base de código acabar usando type em algum lugar, seja lá o que use para formatos de objeto.

O que só a interface faz: declaration merging

Duas declarações interface com o mesmo nome no mesmo escopo se combinam em uma. Duas declarações type com o mesmo nome geram o erro TS2300, Duplicate identifier.

interface Settings {
  theme: string;
}
interface Settings {
  fontSize: number;
}
const s: Settings = { theme: "dark", fontSize: 14 }; // needs both

type Options = { a: number };
type Options = { b: number }; // error TS2300: Duplicate identifier 'Options'.

O merging é como os tipos de bibliotecas são estendidos de fora: acrescentar uma propriedade ao Window global, ao Request do Express ou ao tipo de tema de uma biblioteca. Se você publica tipos que os usuários podem precisar ampliar, use interfaces. No código da sua própria aplicação, uma junção acidental (dois arquivos de script declarando o mesmo nome de interface global) acontece em silêncio, a menos que os dois declarem a mesma propriedade com tipos diferentes, e esse é um dos argumentos que alguns times usam para preferir type.

extends vs intersection

Uma interface estende com extends, um type alias com &. Na maioria das vezes o resultado é o mesmo, mas eles tratam de forma diferente uma propriedade conflitante. O extends aponta o conflito na declaração:

// This does not compile: id cannot change from string to number
interface Base {
  id: string;
  name: string;
}

interface Broken extends Base {
  id: number;
}

const x: Broken = { id: 1, name: "a" };
console.log(x);

index.ts(7,11): error TS2430: Interface 'Broken' incorrectly extends interface 'Base'.
  Types of property 'id' are incompatible.
    Type 'number' is not assignable to type 'string'.

Uma intersection aceita o mesmo conflito em silêncio e transforma a propriedade em never (uma string que também é number). O erro só aparece depois, quando você tenta criar um valor:

type Base = { id: string; name: string };
type Broken = Base & { id: number }; // no error here

// id is string & number, which is never: no object can satisfy Broken
// @ts-expect-error: Type 'number' is not assignable to type 'never'.
const x: Broken = { id: 1, name: "a" };

console.log("the alias compiled; only using it failed");

O erro aponta para o objeto, longe da declaração que o causou. Para montar tipos de objeto a partir de outros tipos de objeto, o extends dá a mensagem melhor.

Index signatures: uma diferença fácil de perder

Um type alias para um tipo de objeto recebe uma index signature implícita, então pode ser passado onde um Record<string, unknown> é esperado. Uma interface não. Isso é proposital: a explicação do time do TypeScript (issue #15300 no repositório do TypeScript) é que uma interface pode ser ampliada por declarações posteriores, então inferir uma index signature para ela é menos seguro, e mudar a regra agora quebraria código demais.

interface UserI { name: string; age: number }
type UserT = { name: string; age: number };

function logFields(fields: Record<string, unknown>) {
  for (const [key, value] of Object.entries(fields)) {
    console.log(`${key}=${String(value)}`);
  }
}

const t: UserT = { name: "Ada", age: 36 };
const i: UserI = { name: "Alan", age: 41 };

logFields(t); // fine

// @ts-expect-error: Index signature for type 'string' is missing in type 'UserI'.
logFields(i);

logFields({ ...i }); // a spread copy is a fresh object type, so it is accepted

A chamada marcada com @ts-expect-error roda mesmo assim e imprime os campos de Alan: a regra vale em tempo de compilação. Esse é o motivo comum de um erro confuso quando um valor de interface é passado para um helper de log, serialização ou consulta tipado com Record<string, ...>. Troque essa declaração específica para type, espalhe o valor com spread ou tipe o parâmetro do helper com uma interface ou um generic.

Desempenho e mensagens de erro

A página Performance da wiki do TypeScript (seção "Preferring Interfaces Over Intersections") sugere interface Foo extends Bar, Baz { ... } em vez de type Foo = Bar & Baz & { ... } ao compor tipos de objeto. Os motivos: uma interface é um único tipo de objeto plano que detecta conflitos de propriedades, as relações de tipo entre interfaces ficam em cache (intersections como um todo não ficam), e verificar um valor contra uma intersection verifica cada componente antes do tipo achatado. A diferença importa em bases de código grandes com muitos tipos compostos; com alguns formatos de objeto comuns você não vai conseguir medi-la.

A mesma página observa que interfaces aparecem melhor. Uma interface é mostrada pelo nome nos tooltips e nas mensagens de erro, enquanto um alias de intersection muitas vezes é impresso expandido em suas partes, o que deixa mensagens longas mais difíceis de ler.

Qual usar

Uma regra que funciona:

1. Formatos de objeto: interface. Ela dá extends verificado, erros mais claros em composições grandes e permite que usuários de bibliotecas a ampliem. Isso segue a heurística do handbook do TypeScript: "use interface until you need to use features from type".
2. Todo o resto: type. Unions, tuplas, tipos de função, literal types e tudo o que é montado com mapped, conditional ou template literal types.
3. Exceção: use type para um formato de objeto que precisa caber em parâmetros Record<string, ...>, ou quando você quer impedir o merging de propósito.

Usar type para tudo também é uma escolha coerente, e muitas bases de código fazem isso. Misturar os dois ao acaso é a única opção a evitar: faz quem lê se perguntar se havia uma diferença intencional.