Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
export {};

declare global {
  interface Array<T> {
    last(): T | undefined;
  }
}

Try it

TypeScript Extending a built-in interface

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.

TypeScript Adding a global variable

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

TypeScript
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 var for globals you want to read as globalThis.name without a type error under --strict; let and const inside declare global are legal but not properties of globalThis.
  • Browser example (read-only): declare global { interface Window { dataLayer: unknown[] } } lets window.dataLayer type-check in a browser project. The Node runner on this site has no window, so such code cannot run here.
  • Environment variables: augmenting NodeJS.ProcessEnv types process.env.KEY as 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.ts or global.d.ts file included by your tsconfig.json, and keep it a module with export {}.