TypeScript Interface Vs Type FAQ & Answers

Performance differences (2025): (1) Type-checking speed - interfaces use nominal identity (cached by name), types require full structural comparison, 15-30% faster type-checking for interface-heavy codebases (>50K types), (2) Error messages - interfaces display as declared name, types expand inline, 50-80% less verbose errors with interfaces, (3) IDE autocomplete - interfaces 20-40% faster intellisense in VS Code/WebStorm (pre-computed type caches), (4) Declaration file size - interfaces more compact (.d.ts files), types expand inline, 30-60% larger declaration files with types.

Declaration merging: TypeScript combines multiple interface declarations with same name in same scope into single type. Use cases: (1) Third-party augmentation - extend global types: declare global { interface Window { myAPI: MyAPI; } }, Express Request: declare module 'express' { interface Request { user?: User; } }, (2) Plugin architectures - each plugin adds methods to shared interface, (3) Incremental API design - split large interfaces across files, (4) Backwards compatibility - add properties without breaking existing declarations. Type aliases cannot merge (redeclaration error).

Use interface for: (1) Object shapes (POJOs, DTOs), (2) Class contracts (implementing classes), (3) Public APIs (better error messages), (4) Extensible types (plugin APIs, global types), (5) Performance-critical codebases (>100K LOC). Use type for: (1) Unions (type Status = 'pending' | 'active'), (2) Intersections (type Admin = User & Permissions), (3) Mapped types (Readonly), (4) Tuple types (type Point = [number, number]), (5) Utility types (Pick, Omit, Partial), (6) Primitive aliases (type ID = string | number), (7) Template literal types.

2025 best practice: Use interface for object definitions (data models, API responses, component props), type for everything else (unions, utilities, complex transformations). Performance benchmarks (>500K LOC): interface-first approach shows 25-35% faster type-checking, 40-50% smaller .d.ts files, 20-30% lower IDE memory usage. Framework conventions: React (interface for props), Vue (interface for defineProps), Angular (interface for services/models), Next.js (interface for page props).

ESLint @typescript-eslint/consistent-type-definitions rule enforces consistent choice (interface or type). Configure based on project size: interface for large projects (>100K LOC, performance benefit), flexible for small projects. Migration strategy for large codebases: use ts-migrate or jscodeshift for automated refactoring, preserve type for unions/intersections/utilities, measure type-checking improvement with --extendedDiagnostics before/after. TypeScript 5.x: better caching for both, but interface performance advantage remains for object shapes.

Performance differences (2025): (1) Type-checking speed - interfaces use nominal identity (cached by name), types require full structural comparison, 15-30% faster type-checking for interface-heavy codebases (>50K types), (2) Error messages - interfaces display as declared name, types expand inline, 50-80% less verbose errors with interfaces, (3) IDE autocomplete - interfaces 20-40% faster intellisense in VS Code/WebStorm (pre-computed type caches), (4) Declaration file size - interfaces more compact (.d.ts files), types expand inline, 30-60% larger declaration files with types.

Declaration merging: TypeScript combines multiple interface declarations with same name in same scope into single type. Use cases: (1) Third-party augmentation - extend global types: declare global { interface Window { myAPI: MyAPI; } }, Express Request: declare module 'express' { interface Request { user?: User; } }, (2) Plugin architectures - each plugin adds methods to shared interface, (3) Incremental API design - split large interfaces across files, (4) Backwards compatibility - add properties without breaking existing declarations. Type aliases cannot merge (redeclaration error).

Use interface for: (1) Object shapes (POJOs, DTOs), (2) Class contracts (implementing classes), (3) Public APIs (better error messages), (4) Extensible types (plugin APIs, global types), (5) Performance-critical codebases (>100K LOC). Use type for: (1) Unions (type Status = 'pending' | 'active'), (2) Intersections (type Admin = User & Permissions), (3) Mapped types (Readonly), (4) Tuple types (type Point = [number, number]), (5) Utility types (Pick, Omit, Partial), (6) Primitive aliases (type ID = string | number), (7) Template literal types.

2025 best practice: Use interface for object definitions (data models, API responses, component props), type for everything else (unions, utilities, complex transformations). Performance benchmarks (>500K LOC): interface-first approach shows 25-35% faster type-checking, 40-50% smaller .d.ts files, 20-30% lower IDE memory usage. Framework conventions: React (interface for props), Vue (interface for defineProps), Angular (interface for services/models), Next.js (interface for page props).

ESLint @typescript-eslint/consistent-type-definitions rule enforces consistent choice (interface or type). Configure based on project size: interface for large projects (>100K LOC, performance benefit), flexible for small projects. Migration strategy for large codebases: use ts-migrate or jscodeshift for automated refactoring, preserve type for unions/intersections/utilities, measure type-checking improvement with --extendedDiagnostics before/after. TypeScript 5.x: better caching for both, but interface performance advantage remains for object shapes.