typescript-interface-vs-type_skill

Overview

This skill guides when to choose TypeScript's interface versus type alias. It summarizes recommended defaults, key differences, and practical rules for defining object shapes, extending types, and using advanced type features. Follow these guidelines to improve type clarity, error detection, and compiler performance.

How this skill works

The skill inspects common type-design scenarios and recommends interface by default for object shapes and extension. It highlights cases where type aliases are required (unions, mapped, conditional, tuple, or certain function shapes). It also prefers interface extends over type intersections for clearer errors and faster type-checking.

When to use it

• Use interface for plain object type definitions and class implementations.
• Use interface when you need declaration merging or repeated augmentation.
• Use type when you require unions, mapped types, conditional types, or tuples.
• Use type for complex function signatures when more convenient than interface.
• Prefer interface extends when creating derived object types rather than using & intersection.

Best practices

• Default to interface for object shapes; switch to type only for features interfaces can't express.
• Prefer interface extends over type intersections to catch incompatible properties at definition time.
• Avoid unnecessary intersections; they can degrade TypeScript performance on large codebases.
• Use named interfaces for reuse and clearer error messages; keep type aliases for compositional or computed types.
• Keep unions and conditional logic in type aliases to make intent explicit and maintainable.

Example use cases

• Define a reusable object contract implemented by classes: use interface.
• Create a discriminated union of request states: use type with union literals.
• Build a readonly version of an API response: use a mapped type via type alias.
• Extend a user object into an admin with extra permissions: prefer interface extends.
• Model tuple-based coordinates or fixed-length arrays: use type alias for the tuple.