# Typescript Interface Vs Type

> Guides when to use interface vs type in TypeScript. Use this skill when defining object types, extending types, or choosing between interface and type aliases. Use when this capability is needed.

- Skill: `tomevault-io/typescript-interface-vs-type` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/typescript-interface-vs-type`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/typescript-interface-vs-type/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/typescript-interface-vs-type

---


# TypeScript: Interface vs Type

## Core Principle

**Use `interface` until you need features from `type`.**

This is the official TypeScript recommendation from the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html).

## When to Use Interface

Use `interface` for:
- Object type definitions
- Extending other object types
- Class implementations
- Declaration merging (augmenting existing types)

## When to Use Type

Use `type` only when you need:
- Union types: `type Status = 'pending' | 'approved' | 'rejected'`
- Mapped types: `type Readonly<T> = { readonly [K in keyof T]: T[K] }`
- Conditional types: `type NonNullable<T> = T extends null | undefined ? never : T`
- Tuple types: `type Point = [number, number]`
- Function types (though interface can also work): `type Handler = (event: Event) => void`

## Prefer `interface extends` Over Intersection (`&`)

When extending object types, always prefer `interface extends` over type intersections.

```typescript
// Preferred
interface User {
  name: string;
}

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

// Avoid
type User = {
  name: string;
};

type Admin = User & {
  permissions: string[];
};
```

### Reason 1: Better Error Messages

With `interface extends`, TypeScript raises errors at the definition when extending with incompatible properties:

```typescript
interface Base {
  id: number;
}

// Error immediately at definition
interface Extended extends Base {
  id: string; // Error: Type 'string' is not assignable to type 'number'
}
```

With intersections, errors only appear when accessing the incompatible property, making bugs harder to catch:

```typescript
type Base = {
  id: number;
};

// No error at definition
type Extended = Base & {
  id: string;
};

// Error only when used
const item: Extended = { id: 'abc' }; // Error appears here, not at type definition
```

### Reason 2: Better TypeScript Performance

`interface extends` provides better TypeScript performance:
- Interfaces are cached by name - TypeScript computes the type once and reuses it
- Intersections are recomputed every time they're used, which slows down type checking with complex types

See [TypeScript Performance Wiki](https://github.com/microsoft/TypeScript/wiki/Performance#preferring-interfaces-over-intersections) for details.

## References

- [TypeScript Handbook - Everyday Types](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html)
- [TypeScript Performance Wiki](https://github.com/microsoft/TypeScript/wiki/Performance#preferring-interfaces-over-intersections)
- [Total TypeScript - Intersections vs Interface Extends](https://www.totaltypescript.com/books/total-typescript-essentials/objects#intersections-vs-interface-extends)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/flpbalada) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->