Globals, Namespaces and Module Augmentation

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Global

A name any file can use without importing it, like window.

Script file

A file without top-level import or export: its declarations are global.

Declaration merging

Several declarations of one name (like interfaces) combine into one.

declare global

A block inside a module that adds declarations to the global scope.

Module augmentation

Adding members to the types of an existing module with declare module "x".

Namespace

A named group of values and types in one object-like container.

Window

The type of the browser's global object window.

erasableSyntaxOnly

A setting that bans TypeScript syntax that needs more than deleting types, such as namespaces and enums.

1. 1

   Add a property

   In the second example add theme: "light" | "dark"; to Window, then write window.theme = "blue";. Predict the error before you look: TS2322, because "blue" is not one of the two strings.

2. 2

   Merge a clash

   In the third example, add a third interface Box { width: string }. Predict: tsc complains that two declarations of width have different types (TS2717, subsequent property declarations must have the same type).

3. 3

   Peek inside a namespace

   In the fourth example, try Geometry.circle(2) + Geometry.secret. A name that wasn't exported isn't visible. Add const secret = 1; inside the namespace first, then see the error.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: sometimes a name exists at run time that TypeScript did not create (window.appVersion set by a script tag), or a library needs a new field from a plugin. These features let you tell the checker, instead of silencing it with any. (Recall from Topic 11.3: declare is a promise that something exists.) A global is a name any file can use without importing it, such as window, document, console or process. Their types come from declaration files that are scripts: files with no top-level import/export (Topic 11.1), so everything declared inside goes into the shared global scope. lib.dom.d.ts is one. If you want your own global (a __APP_VERSION__ constant your bundler replaces), put declare const __APP_VERSION__: string; in a script .d.ts (real run: it worked; adding a single export {} to the same file made it a module and then Cannot find name '__APP_VERSION__' appeared).

2. 2

   Declaration merging is a TypeScript rule: two interface declarations with the same name in the same scope become one interface with all the members. This is why Window, Array and HTMLElementTagNameMap can be extended by anyone. type aliases do not merge (a second one is a duplicate-name error). The live example below merges two Box interfaces. Members you add must not clash: the same property with a different type is an error.

3. 3

   Inside a module file you can't write a plain interface Window { … }, because that would create a new local Window. To reach the global scope from a module use **declare global { … }**. Everything inside is added to the global declarations. A typical use: declare global { interface Window { appVersion: string } } after which window.appVersion type-checks. Without it you get TS2339: Property 'appVersion' does not exist on type 'Window & typeof globalThis' (real). Remember it is still a promise: you must set window.appVersion yourself at runtime. In a declare global block, var (not let/const) is how you declare a global variable that is also a property of globalThis.

4. 4

   Module augmentation is the same idea for a package: in a module file write declare module "shapes" { interface Options { color?: string } } and the package's Options interface gains color. In the real test project, draw({ size: 2, color: "red" }) first failed with TS2353 (excess property) and compiled after the augmentation file existed. The file must be a module (import "shapes"; at the top is the usual way), and the augmentation can only *add* to interfaces and namespaces, not replace functions or change existing members. This is how plugins extend Express's Request, Vue's component options and other libraries.

5. 5

   A namespace (namespace Geometry { export const PI = 3.14 }) groups names under one object. It was TypeScript's answer to modules before ES modules existed. Now modules do that job, and namespaces are mostly found in old code and in .d.ts files that describe a library's global object. A namespace can merge with a function, class or enum of the same name (the live example adds a property to a function through namespace greet). Note: a namespace emits runtime code, an object plus a function wrapper, so it isn't erased. That is why erasableSyntaxOnly (since 5.8, for tools like Node that only strip types) reports TS1294 on it, as it does for enum and parameter properties.

6. 6

   Writing the keyword module for a namespace (module Legacy { … }) is an error: both TypeScript 6.0.3 and 7.0.2 report TS1540: A 'namespace' declaration should not be declared using the 'module' keyword. Please use the 'namespace' keyword instead. (real). In a new project, write ES modules and use declare global or augmentation only for the few things that really are global.

• ↔

  Augmenting globals is a convenient way to type environment facts (bundler constants, injected objects) but anyone in the program can see and depend on them. Keep each in one file with a comment saying who sets it.

• ↔

  Augmenting a library's interface is the supported way to write plugins, but if the library renames or moves that interface, your augmentation silently stops applying and the new field becomes an error somewhere else.

• I can explain script vs module files for global declarations.

• I can write declare global to add to Window.

• I can explain declaration merging, and which declarations merge.

• I can write a module augmentation and say what it cannot do.

• I can read a namespace and say why modules replaced them.