ReviseAlgo Logo

Objects & Interfaces

Declaration Merging

Master interface declaration merging in TypeScript, augmenting third-party library types, namespace merging, and global scope expansion.

Last Updated: July 29, 2026 • 10 min read
Declaration Merging is a unique TypeScript feature where the compiler automatically combines two or more separate declarations with the same name into a single, unified type definition.

Declaration merging is widely used to augment global browser interfaces (like Window or ProcessEnv) and extend third-party library types without modifying source files in node_modules.

1. How Interface Declaration Merging Works

When two interfaces share the exact same identifier in the same namespace, TypeScript merges their properties:

2. Real-World Use Case: Augmenting Global Window and ProcessEnv

In web and Node.js applications, you frequently attach custom global variables (e.g. Google Analytics gtag, or custom environment variables). Use interface declaration merging to type them safely:

Augmenting global Window

Augmenting Node.js process.env

3. Merging Method Signatures

When merging interfaces containing methods, the merged method signatures act as Function Overloads. Later declarations take precedence over earlier declarations.

4. Interactive Code Playground

Test declaration merging below:

5. Common Pitfalls & Edge Cases

  • Non-Function Property Conflicts: If two merged interface declarations define the same property name with non-identical, incompatible types, TypeScript raises a compile error.

    • 6. Summary Table

    Merge TypeSupported?Description
    Interface + InterfaceYesMerges properties into single interface
    Namespace + NamespaceYesMerges exported namespace members
    Class + InterfaceYesAdds interface properties to class shape
    | Type + Type | No | Compile Error: Duplicate identifier |