Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Concepts and Comparisons

Declaration merging in TypeScript

How TypeScript merges declarations that share a name: interfaces, namespaces with classes, functions and enums, and module augmentation.

When two declarations in the same scope have the same name, TypeScript sometimes combines them into one definition instead of reporting a duplicate. This is declaration merging. It is how a library can add properties to Window, how Express middleware extends Request, and how a function can carry static members.

Not every kind of declaration merges. Interfaces merge with interfaces, namespaces merge with classes, functions and enums, and enums merge with enums. Type aliases and let/const never merge.

TypeScript
interface Box { width: number }
interface Box { height: number }
// Box now has both width and height

Try it

TypeScript Interface merging

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Namespace plus function, enum or class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

What merges

Declarations Result
interface + interface One interface with all members
namespace + namespace One namespace; exported members combine
namespace + class Static-like members on the class (the namespace comes after the class)
namespace + function Properties on the function (namespace after the function)
namespace + enum Extra members on the enum object
enum + enum Members combine; rarely useful
class + interface The interface adds instance members to the class type
type alias + anything Error: duplicate identifier

Merging rules for interfaces

  • Non-function members must be unique or have identical types. A repeated property with a different type is error TS2717.
  • Method overloads merge, and later interface declarations' overloads are placed first in the list.
  • String-literal overloads are hoisted higher still, so specific signatures win.
  • Generic parameters must match exactly across declarations.

Usage notes

  • Module augmentation: inside a module, declare module "pkg" { interface Foo { ... } } merges with the library's interface; see Module augmentation.
  • Global augmentation: declare global { interface Window { ... } } inside a module file; see Global augmentation.
  • Namespace merging is order dependent: a namespace that merges with a class or function must come after it in the same file.
  • Class + interface merging can hide missing implementations: the interface members satisfy the class type with no code behind them.
  • Types only: merging is a type-level feature, and the emitted JavaScript for merged namespaces follows the usual namespace pattern.
  • Prefer modules and normal imports for new code; use merging for augmenting types you do not own.