Adding Properties to Existing Interfaces
What you'll learn: How to extend interfaces exported by a module using declaration merging within a module augmentation block.
The Core Idea
Sometimes you need to add properties to an interface that comes from a third-party library or another module you don't control. TypeScript lets you do this through module augmentation combined with declaration merging—you can "reopen" a module and add new properties to its exported interfaces without modifying the original source.
How It Works
You use declare module 'module-name' to create an augmentation block, then redeclare the interface inside with your additional properties. TypeScript merges these declarations automatically:
// Imagine a library 'user-lib' exports this:
// export interface User {
// name: string;
// }
// In your code, you can augment it:
declare module 'user-lib' {
interface User {
lastLogin: Date;
}
}
// Now User has both 'name' and 'lastLogin'
import { User } from 'user-lib';
const user: User = {
name: "Alice",
lastLogin: new Date()
};
Both properties are now required. The original interface and your augmentation merge into a single type.
When This Is Useful
This pattern shines when:
- A library's types are incomplete for your use case
- You're adding plugin functionality to a framework
- You need to track additional metadata across your app
- You're gradually migrating types in a large codebase
Key Takeaway: Module augmentation with declaration merging lets you non-invasively add properties to third-party interfaces, seamlessly blending your additions with the original type definitions.