Declaration Merging

Reviewed & published by Brayan K

Declaration merging is TypeScript's rule that two or more declarations sharing the same name are automatically combined into one definition, letting you extend interfaces, attach statics to functions, and augment library or global types.

Part of the free TypeScript course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

What You'll Learn

• Merge two interfaces of the same name so their members combine
• Merge a function with a namespace to attach static members
• Augment a third-party module with declare module "lib"
• Augment the global scope with declare global (Window, Express)
• Add req.user typing to Express the idiomatic way
• Know when merging applies — and why type aliases never merge

💡 Real-World Analogy

Think of declaration merging like adding pages to a shared binder. Two people each bring a few pages labelled "Box"; instead of fighting over the label, TypeScript files all the pages under "Box" so the binder now contains everyone's contributions. That's why a library can ship a base Request interface and your code can quietly slip in an extra user page — same label, combined contents.

1. Function + Namespace Merging

When a function and a namespace share a name, TypeScript merges them: the function stays callable and also gains the namespace's exported members as static properties. This is the type-safe way to describe a callable value that carries helpers — like jQuery's $ being both a function and a bag of utilities. At runtime it's simply a function object with extra properties attached.

// TWO declarations with the SAME name merge into one. A function declaration
// and a namespace of the same name combine — the function gains static members:

function greet(name: string): string {
  return greet.prefix + name;
}
namespace greet {
  export let prefix = "Hello, ";
  export function shout(name: string): string {
    return greet(name).toUpperCase();
  }
}

greet("Ada");        // "Hello, Ada"  — callable
greet.prefix;        // "Hello, "     — static property
greet.shout("Ada");  // "HELLO, ADA"  — static method

// Declaration merging is a COMPILE-TIME feature, but the runtime behaviour it
// mirrors is real. The classic "function + namespace" merge produces ONE value
// that is both CALLABLE and carries extra static properties.

// A callable object with statics — exactly what TS lets you describe with merging:
function greet(name) {
  return greet.prefix + name;
}
greet.prefix = "Hello, ";          // a "namespace" property bolted onto the function
greet.shout = (name) => greet(name).toUpperCase();

console.log(greet("Ada"));         // Hello, Ada
console.log(greet.prefix);         // Hello,
console.log(greet.shout("Ada"));   // HELLO, ADA

// Merging interfaces is just "all members combine" — two shapes become one value:
const a = { id: 1 };
const b = { name: "widget" };
const merged = { ...a, ...b };     // one value with BOTH sets of members
console.log(merged.id, merged.name); // 1 widget

2. Interface Merging & Augmenting Globals

Two interfaces with the same name merge their members into one larger interface — there's no duplicate error, unlike with type aliases. This is the engine behind global augmentation: you reopen a built-in interface like Window and add your own properties so the compiler knows about values you attach at runtime.

// Two INTERFACES with the same name MERGE — their members are combined.
// (Two type aliases with the same name would instead be a duplicate error.)
interface Box {
  width: number;
}
interface Box {
  height: number;          // merged in — Box now has BOTH
}

// Box is now { width: number; height: number }
const b: Box = { width: 10, height: 5 }; // ✅ must satisfy the MERGED interface
// const bad: Box = { width: 10 };       // ❌ Property 'height' is missing

// AUGMENTING a global. In TS you write
//   declare global { interface Window { appConfig: Config } }
// to TELL the compiler about a property your code adds at runtime.
// The RUNTIME part is simply the assignment — here we use a plain object as "window".

const windowLike = {}; // pretend this is the global 'window'

// Some setup code adds a property at runtime:
windowLike.appConfig = { theme: "dark", version: 3 };

// Now any code can read it (and TS would know its type thanks to the augmentation):
console.log(windowLike.appConfig.theme);   // dark
console.log(windowLike.appConfig.version); // 3

// Express does the SAME: middleware sets req.user, and a global augmentation
// makes TypeScript aware of it. Runtime = just an assignment:
const req = { headers: {} };
function authMiddleware(req) { req.user = { id: 42, name: "Ada" }; }
authMiddleware(req);
console.log(req.user.id, req.user.name); // 42 Ada

3. Module Augmentation (Express & Beyond)

To extend types that live in another package, use module augmentation. Wrapping a declaration in declare module "express" (or declare global { namespace Express { ... } }) merges new members into that library's interfaces. The canonical use is teaching TypeScript about req.user set by your auth middleware.

// MODULE AUGMENTATION adds members to types declared in ANOTHER module.
// The famous example: teaching TypeScript about req.user on Express.
import "express";

declare global {
  namespace Express {
    interface Request {
      user?: { id: number; name: string }; // merged into Express's Request
    }
  }
}

// Now every handler sees req.user as fully typed:
// app.get("/me", (req, res) => res.json(req.user)); // ✅ req.user is known

// To augment a non-global module, target it by name instead:
declare module "express" {
  interface Request {
    requestId?: string;
  }
}

🎯 Your Turn

Build your own function + namespace merge: a callable counter() that bumps a count, plus a .reset() static. Fill in the two blanks marked ___, then run it.

// 🎯 YOUR TURN — replace each ___ then press "Try it Yourself".
// Build a "function + namespace" merge: a callable counter that ALSO
// carries a .reset() static and a .count property.

function counter() {
  counter.count = counter.count + 1;   // bump the static count
  return counter.count;
}
counter.count = 0;                       // the "namespace" property
counter.reset = () => { counter.count = ___; }; // 👉 reset back to 0

console.log(counter());   // 1
console.log(counter());   // 2
counter.reset();
console.log(counter.___); // 👉 read the 'count' property -> 0

// ✅ Expected output:
//    1
//    2
//    0

Common Errors (and the fix)

• ❌ "Duplicate identifier 'Box'" — you declared the same type Box twice. ✅ Use interface Box (interfaces merge; type aliases don't).
• ❌ "Property 'user' does not exist on type 'Request'" — Express doesn't know about your field. ✅ Add declare global { namespace Express { interface Request { user?: User } } }.
• ❌ "Augmentations for the global scope can only be... in module files" — your .d.ts has no imports/exports. ✅ Add an export {} at the top so the file is a module.
• ❌ Forgetting the runtime assignment — typing req.user doesn't set it. ✅ Your middleware must still do req.user = ...; merging only adds the type.

Pro Tips

• 💡 Prefer interface for public, library-facing shapes precisely because consumers can merge into them later.
• 💡 Keep augmentations in a dedicated types/express.d.ts so it's obvious where global additions live.
• 💡 A class can merge with a namespace to add static members or nested types — handy for "static-only" companions.
• 💡 An enum can merge with a namespace to attach helper functions to the enum object.

📚 Keep Learning

• 📖 TypeScript Handbook — Declaration Merging
• 📖 Writing module .d.ts declaration files
• 📖 Handbook — Extending Types & Interfaces

Mini-Challenge: A Money Formatter With Statics

No blanks this time — just a brief and a starting outline. Build the function + namespace merge yourself, run it, and check your output against the example in the comments.

// 🎯 MINI-CHALLENGE: a function + namespace merge for a money formatter.
// 1. Make money(amount) return money.currency + amount.toFixed(2).
// 2. Attach money.currency = "£" and money.withCurrency(sym, amount)
//    that uses a given symbol instead of the default.
// 3. Log money(5), money.currency, and money.withCurrency("$", 5).
//
// ✅ Expected output:
//    £5.00
//    £
//    $5.00

// your code here

🎉 Lesson Complete

• ✅ Two declarations with the same name merge into one definition
• ✅ Same-name interfaces combine their members; type aliases don't merge
• ✅ A function + namespace merge gives a callable value with static members
• ✅ declare global reopens built-ins like Window to add your own properties
• ✅ Module augmentation (declare module "express") is how you type req.user

Practice quiz

Continue this course

• Previous: Checkpoint: Type-Level Patterns
• Next: Namespaces — Group code with namespaces, and why ES modules are usually better
• Quick reference: TypeScript cheat sheet

Frequently asked questions

What exactly is declaration merging?

It is TypeScript's rule that two or more declarations with the SAME name in the same scope are combined into a single definition. The most common case is two interfaces with the same name merging their members, but functions, namespaces, classes, and enums can merge with each other in specific combinations too.

Can I merge two type aliases the same way I merge interfaces?

No. Only interfaces (and namespaces, and a few function/class/enum combinations) merge. Declaring the same 'type' alias twice is a duplicate-identifier error. If you need open-ended, augmentable types — for example to let other code extend your shape — use an interface, not a type alias.

How do I add a property to req on Express or to Window?

Use global declaration merging. Write 'declare global { namespace Express { interface Request { user?: User } } }' in a .d.ts (or any module file) to add req.user, or 'declare global { interface Window { appConfig: Config } }' for window.appConfig. You're merging your members into the library's existing interface; the runtime assignment is still your job.

What is module augmentation and how is it different?

Module augmentation uses 'declare module "some-lib" { ... }' to merge new members into types exported by another module. It's how plugins extend a library's types (e.g. adding a method to a third-party class). Global augmentation ('declare global { ... }') targets the global scope instead of a specific module.

Related lessons

• Interfaces