← All notes

Answer: Declaration merging means the TypeScript compiler combines two or more declarations with the same name into one definition that has the features of all of them.

Interface merging

interface Box { height: number }
interface Box { width: number }
const b: Box = { height: 1, width: 2 };

Any number of declarations can merge. Non-function members of the interfaces should be unique. (S1)

Namespaces with classes, functions or enums

function greet() {}
namespace greet { export const version = 1; }
greet.version;

Module augmentation

import "express";
declare module "express" {
  interface Request { user?: { id: string } }
}

Global augmentation

declare global { interface Window { appVersion: string } }
export {};

Not mergeable

Classes cannot merge with other classes; use mixins. While it won't change any behavior at runtime, a property marked as readonly can't be written to during type-checking. (S2)

Claims

• id: C1 claim: Declaration merging merges two declarations with the same name. source: S1 evidence: "means that the compiler merges two separate declarations declared with the same name into a"
• id: C2 claim: Any number of declarations can be merged. source: S1 evidence: "Any number of declarations can be merged; it’s not limited to just two declarations."
• id: C3 claim: Global augmentations have the same limits as module augmentations. source: S1 evidence: "Global augmentations have the same behavior and limits as module augmentations."
• id: C4 claim: A readonly property can't be written during type-checking. source: S2 evidence: "a property marked as readonly can’t be written to during type-checking"

Sources

• [S1] TypeScript: Documentation - Declaration Merging. TypeScript (Microsoft). https://www.typescriptlang.org/docs/handbook/declaration-merging.html . License: CC BY 4.0 (microsoft/TypeScript-Website). Accessed 2026-11-04.
• [S2] TypeScript: Documentation - Object Types. TypeScript (Microsoft). https://www.typescriptlang.org/docs/handbook/2/objects.html . License: CC BY 4.0 (microsoft/TypeScript-Website). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

@misc{iil_note_er92xbyq,
  author = {{iinventedlight}},
  title = {{Declaration merging in TypeScript}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-04},
  url = {https://iinventedlight.com/library/notes/typescript-declaration-merging/},
  note = {Permanent ID iil:note:er92xbyq. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/typescript-declaration-merging.md.