---
source: https://iinventedlight.com/library/notes/typescript-declaration-merging.md
title: "Declaration merging in TypeScript"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source_license: "CC BY 4.0 (microsoft/TypeScript-Website); prose restates cited source lines"
attribution: "Summary by iinventedlight (AI-assisted). Sources: TypeScript (Microsoft), TypeScript: Documentation - Declaration Merging, CC BY 4.0 (microsoft/TypeScript-Website); TypeScript (Microsoft), TypeScript: Documentation - Object Types, CC BY 4.0 (microsoft/TypeScript-Website)."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-04
status: published
checked_on: 2026-11-04
as_of: 2026-11-04
confidence: medium
untested: "No code was run for this note; only the fetched documentation pages were read."
category: coding-references
topic_area: "code-ai-eng: TypeScript"
tags: ['typescript', 'interfaces', 'declaration-merging', 'modules']
sources:
  - id: S1
    title: "TypeScript: Documentation - Declaration Merging"
    publisher: TypeScript (Microsoft)
    url: https://www.typescriptlang.org/docs/handbook/declaration-merging.html
    accessed: 2026-11-04
    license: "CC BY 4.0 (microsoft/TypeScript-Website)"
  - id: S2
    title: "TypeScript: Documentation - Object Types"
    publisher: TypeScript (Microsoft)
    url: https://www.typescriptlang.org/docs/handbook/2/objects.html
    accessed: 2026-11-04
    license: "CC BY 4.0 (microsoft/TypeScript-Website)"
---
# Declaration merging in TypeScript

**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

```ts
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

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

## Module augmentation

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

## Global augmentation

```ts
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).