This post is part of Typescript learners guide.
More about Module Augmentation
typescript module augmentation
1. Module Augmentation
- What It Is: Allows you to extend or modify the functionality of existing modules (third-party libraries or built-in modules).
- How It Works:
- You use the
declare module
syntax to tell TypeScript that you’re adding or modifying properties or types within an existing module. - TypeScript merges your changes with the existing module definitions.
- You use the
- Use Cases:
- Add custom properties to objects from third-party libraries (e.g., adding properties to Express’s
Request
object). - Modify existing interfaces or classes to match specific application requirements.
- Add custom properties to objects from third-party libraries (e.g., adding properties to Express’s
-
Example: Adding a
user
property to theRequest
interface in Express:typescript declare module "express" { interface Request { user?: string; } }
2. Global Module Augmentation
- What It Is: Extends or modifies global objects like
window
(in browsers) orprocess
(in Node.js). - How It Works:
- Use
declare global
within a.d.ts
declaration file to augment global objects. - This applies the modifications globally across your entire application.
- Use
- Use Cases:
- Add custom properties to global objects that are available throughout the application.
-
Example: Augmenting the
window
object in a browser environment:typescript declare global { interface Window { user?: string; } } // Now you can access `window.user` anywhere in your code window.user = "Alice";
3. Key Concepts
- Declaration Merging: When you augment a module or global object, TypeScript merges your new declarations with the original module definitions.
- Type Safety: TypeScript ensures that the augmentations are type-safe, preventing errors when accessing augmented properties.
-
Modifying Existing Modules: You can modify an existing module’s interfaces, classes, or methods without modifying the original module code.
4. Examples of Module Augmentation
- Extending Express’s
Request
object:declare module "express" { interface Request { user?: string; } }
- Augmenting the
process
object in Node.js:typescript declare global { namespace NodeJS { interface Process { myCustomProperty?: string; } } }
5. Why Use Module and Global Augmentation?
- Third-party Libraries: Modify and extend third-party libraries without changing their code.
- Customization: Customize existing global objects to fit your application’s needs (e.g., adding properties to
window
orprocess
). -
Type Safety: TypeScript ensures that your augmentations are compatible with the existing types in the module or global object.
6. Best Practices
- Use
.d.ts
Files: Keep augmentations in separate.d.ts
declaration files to maintain type safety and organization. - Be Cautious with Global Augmentations: Augmenting global objects affects the entire application, so use this feature carefully to avoid conflicts.
- Namespace Management: When augmenting global types (like
process
orwindow
), always use thedeclare global
syntax to avoid conflicts with other modules.
Summary:
- Module Augmentation: Extends or modifies existing modules (e.g., Express, React) to add custom functionality.
- Global Module Augmentation: Extends or modifies global objects (like
window
,process
) to add custom properties accessible across your entire application. - Declaration Merging: TypeScript merges your changes with the original declarations, allowing you to safely extend third-party modules and global objects.