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.
  • 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.

  • Example: Adding a user property to the Request 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) or process (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 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 or process).

  • 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 or window), always use the declare 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.