TypeScript Reference ยท Modules and Declaration Files
TypeScript global augmentation
Reference for TypeScript global augmentation: use declare global in a module to add globals, extend built-in interfaces and add properties to Window.
Global augmentation adds to the global scope from inside a module. You write a declare global { ... } block in a file that has at least one top-level import or export, and everything inside the block merges into the global declarations. You can add new global variables, extend built-in interfaces such as Array<T>, String or Window, and add members to interfaces that other libraries declared globally.
The declaration only changes types. The matching runtime code is your job: if you add Array.prototype.last to the types, you must also define it.
export {}; declare global { interface Array<T> { last(): T | undefined; } }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
declare global { interface Window { analyticsId?: string } // merge into an existing interface var buildTime: number; // new global; must be var function helper(): void; // new global function namespace NodeJS { interface ProcessEnv { API_URL?: string } } }
| Part | Description |
|---|---|
declare global { } |
A block that is only legal inside a module file or another ambient module declaration. |
interface X |
Merges with the existing global interface of the same name. Members are added; conflicting types are errors. |
var name |
Makes the name a property of globalThis. let and const do not, so they are not reachable as globalThis.name. |
namespace N |
Merges into a global namespace such as NodeJS. |
Edge cases: using declare global in a script file (no import or export) is error TS2669 ("Augmentations for the global scope can only be directly nested in external modules or ambient module declarations"). That is why the examples start with export {}.
Usage notes
- Interface merging, not replacement. You can add members to an interface but cannot change or remove existing ones. Two properties with the same name must have identical types.
- Use
varfor globals you want to read asglobalThis.namewithout a type error under--strict;letandconstinsidedeclare globalare legal but not properties ofglobalThis. - Browser example (read-only):
declare global { interface Window { dataLayer: unknown[] } }letswindow.dataLayertype-check in a browser project. The Node runner on this site has nowindow, so such code cannot run here. - Environment variables: augmenting
NodeJS.ProcessEnvtypesprocess.env.KEYas a known optional string. - Prototype patching is risky. Changing built-ins affects every library in the process, can clash with future language features, and breaks if two files add the same method. Prefer a helper function.
- Where to put it. Keep augmentations in one
.d.tsorglobal.d.tsfile included by yourtsconfig.json, and keep it a module withexport {}.