Skip to main content
Global augmentation is a TypeScript mechanism that allows developers to safely inject or modify type declarations in the ambient global scope from within an isolated module. It leverages TypeScript’s declaration merging feature to extend globally available interfaces, variables, or namespaces without altering the runtime execution context. To utilize global augmentation, the file containing the augmentation must be treated by the TypeScript compiler as a module. In TypeScript, any file containing a top-level import or export is considered a module. If a file lacks these, it is treated as a script, and its contents already exist in the global scope, rendering declare global invalid.

​
Syntax

The declare global block is used to escape the local module scope and merge types into the global namespace. 
// 1. Establish module context
export {}; 

// 2. Open the global augmentation block
declare global {
    // 3. Declare or extend global entities
    
    // Extending an existing built-in global interface via declaration merging
    interface Window {
        newProperty: string;
    }

    // Declaring new global variables
    // 'var' declarations become properties on the global object (e.g., window/globalThis)
    var __AMBIENT_VAR__: number;

    // 'let' and 'const' declarations enter the global lexical scope 
    // without becoming properties of the global object, matching ES6+ semantics
    const __AMBIENT_CONST__: string;
    let __AMBIENT_LET__: boolean;

    // Extending an existing global namespace
    namespace NodeJS {
        interface ProcessEnv {
            CUSTOM_ENV_VAR: string;
        }
    }
}

​
Technical Constraints and Rules

1. Module Context Requirement The declare global syntax is strictly scoped to modules. If you attempt to use declare global in a script file (a file without imports/exports), the TypeScript compiler will throw the error: Augmentations for the global scope can only be directly nested in external modules or ambient module declarations. 2. Declaration Merging Limitations Global augmentation relies entirely on TypeScript’s declaration merging. Therefore, you can only augment entities that support merging:
  • Interfaces: Can be merged. You can add new properties or methods to existing global interfaces (like Window, String, or Array).
  • Namespaces: Can be merged.
  • Type Aliases: Cannot be merged. You cannot use global augmentation to extend a type definition.
  • Classes: Cannot be merged directly via augmentation, though their corresponding interfaces can be.
3. Variable Declarations When declaring new global variables within a declare global block, you can use var, let, or const. TypeScript accurately models standard ES6+ JavaScript semantics: variables declared with var will map to properties on the global object (globalThis, window, or global), whereas let and const declare types in the global lexical scope but do not become properties of the global object. 4. Ambient Context Code inside declare global is inherently ambient. It only provides type information to the compiler and emits no JavaScript. The actual runtime implementation of the augmented properties or variables must be handled separately in the execution environment.
Tired of Poor TypeScript Skills? Fix That With Deep Grasping!Learn More