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.
interface Box { width: number } interface Box { height: number } // Box now has both width and height
Try it
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.
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.