Codectionary / Developer documentation / TypeScript

Interface Declaration Merging

Multiple interface declarations with the same name in the same scope merge into one type. This can support extensible contracts, but conflicting property declarations are errors. Type aliases do not merge this way, and merging creates no runtime object or implementation.

Syntax

interface Settings { theme: string; }
interface Settings { retries: number; }

Examples

Interface Declaration Merging: working example

Run this standalone example after compiling with TypeScript 5.4+ in strict mode, targeting ES2022. Expected result: The program prints dark: 3; Settings requires both theme and retries.

interface Settings { theme: "light" | "dark"; }
interface Settings { retries: number; }
const settings: Settings = { theme: "dark", retries: 3 };
console.log(`${settings.theme}: ${settings.retries}`);
  1. Expected result: The program prints dark: 3; Settings requires both theme and retries.
  2. Both declarations contribute properties to the same interface.
  3. The actual object is supplied separately by the const declaration.

Best practices

  • Use merging intentionally for extension points rather than scattering related declarations unnecessarily.
  • Keep declarations in modules to avoid accidental global name collisions.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

TypeScript Handbook

Specifications & further reading