TypeScript · Function

Declaration Merging

Declaration merging combines compatible same-named TypeScript declarations into one definition. It supports patterns such as interface extension by repeated declarations, namespace combination, and module augmentation.

How it works

TypeScript combines compatible declarations that share a name into one definition. The result depends on the declaration kinds: interfaces join members, namespaces can add exported members, and module augmentations patch existing declarations; unsupported or conflicting combinations produce errors.

Syntax

interface Name { ... }
interface Name { ... }

namespace Name { ... }

// Module augmentation
declare module "module-name" { ... }

Key points

The compiler can turn same-named declarations into one combined definition.
A merge may involve three or more declarations.
Declarations create namespace, type, and/or value meanings, which determines possible merge combinations.
Interface merging is the most common form and combines interface members.
Namespaces can combine exported members, including exported interfaces, into a single namespace.
Runtime JavaScript still needs an actual object update when a type-level module patch is accompanied by behavior.

Common mistakes

Repeated non-function properties must have compatible types; otherwise the merge fails.
A namespace must come after the class, function, or enum it augments.
Class-to-class and class-to-variable merging is not supported.
Module augmentation can extend an existing declaration but cannot introduce a new top-level symbol.

Example: Merging interface declarations

interface User {
  id: string;
}

interface User {
  displayName: string;
}

const user: User = { id: "u1", displayName: "Ada" };
console.log(user.displayName);

The two declarations combine into one User interface, so objects must provide members from both declarations.

When to use it

Incrementally extend shared interfaces

Add properties to an interface across separate files or feature modules without editing its original declaration.

Combine namespaces with declarations

Attach static-like namespaces or exported helpers to an existing function, class, or enum.

Patch external module types

Add type information for a library plugin or missing third-party module member.

Model JavaScript APIs

Describe callable and constructable declaration patterns in declaration files where supported.

Interview questions

QWhat is declaration merging?

Declaration merging combines separate declarations with the same name into one definition, and the merged result exposes features from each declaration. Multiple declarations can participate, not only two.

Follow-up: Which interface members may conflict? Non-function members must be unique, while repeated function members are treated as overloads.

QHow does interface merging work?

Interface merging mechanically joins the members of declarations with the same interface name. A repeated non-function member is allowed only when its type agrees across declarations.

Follow-up: What happens to repeated methods? They contribute overload signatures, with later declarations generally ordered before earlier ones in the overload set.

QWhat are module augmentations used for?

Module augmentation lets a declaration patch an existing module, and its declarations merge as though written beside the original. The augmentation cannot add a new top-level declaration.

Follow-up: How is the target module found? Its name follows the same resolution rules as module specifiers used by import and export.

interface merging
namespace merging
module augmentation
global augmentation
Mixins in TypeScript

Source: Declaration Merging. Checked 2026-10-15.