Ambient Declarations

Ambient Declarations — the core idea

Ambient declarations tell the compiler that a variable, function, or module exists elsewhere at runtime. declare emits no implementation. This is useful for host-provided globals, but it is a promise the host must actually satisfy.

What you’ll learn

Explain ambient declarations with a concrete use case.
Run the example and account for every line of its output.
Recognize the difference between compile-time checking and runtime behavior.

Understand the rules and when to use them

Reading the code: HOST_MODE is a declaration only and is intentionally not read, since this local Node example does not supply that global. actualMode is a real initialized value and prints DEVELOPMENT.

Keep the boundary clear: Reading an ambient global that does not exist at runtime produces a ReferenceError; a declaration cannot manufacture it.

See the idea as a flow

Follow the three stages and identify what happens in TypeScript versus JavaScript.

Run the complete TypeScript example

Save the code as ambient-declarations.ts. The result below was captured after compiling this exact example with strict TypeScript checking and executing the emitted JavaScript in Node.js.

TypeScript code

declare const HOST_MODE: string;
const actualMode = "development";
console.log(actualMode.toUpperCase());

Verified output

DEVELOPMENT

Build: npx tsc --strict --target es2022 --module commonjs --lib es2022,dom,esnext.disposable ambient-declarations.ts; run: node ambient-declarations.js. The exact filename may be changed freely. When a multi-file project exists, prefer its tsconfig.json and build scripts.

Trace the example line by line

HOST_MODE is a declaration only and is intentionally not read, since this local Node example does not supply that global. actualMode is a real initialized value and prints DEVELOPMENT.

The output shown above comes from the initialized values in this program. Replacing a type annotation alone does not transform a JavaScript value.

Avoid this common mistake

Reading an ambient global that does not exist at runtime produces a ReferenceError; a declaration cannot manufacture it.

Check both the TypeScript diagnostic and the emitted JavaScript behavior. A program can compile correctly and still need runtime validation or error handling.

Practice independently

Sketch a .d.ts declaration for a global injected by a browser script, then write a fallback check before reading it.

Before running your change, write down the type you expect TypeScript to infer and the output you expect JavaScript to print. Then check both predictions.

What to remember

Ambient declarations tell the compiler that a variable, function, or module exists elsewhere at runtime.

Try the practice change and re-run the exact program to test your understanding.

Reaching the recap and completing the quizzes are separate milestones.

Next lesson: Declaration Merging →