> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TypeScript Global Augmentation
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.
```typescript theme={"dark"}
// 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
