What is ambient declaration?

Ambient declarations in TypeScript provide a way to describe the shapes of existing JavaScript code or libraries, enabling the TypeScript compiler to perform type checking and offer features like intelligent code completion without modifying the original JavaScript implementation.

What are Ambient Declarations?

Ambient declarations, often found in '.d.ts' (declaration) files, are a crucial feature that allows TypeScript projects to safely interact with JavaScript codebases that were not originally written in TypeScript. They serve as a bridge, giving the TypeScript compiler the necessary type information for external JavaScript variables, functions, classes, and modules that exist at runtime.

The core idea is to declare the *existence* and *shape* of these entities to the TypeScript compiler, without actually providing their implementation. This ensures that TypeScript can validate your usage of external libraries, detect potential type errors, and offer accurate type inferences, all at compile time.

The `declare` Keyword

The declare keyword is fundamental to ambient declarations. It is used to signal to the TypeScript compiler that the following variable, function, class, enum, or module already exists somewhere else and should not be compiled into JavaScript. It's purely a compile-time construct.

declare var jQuery: (selector: string) => any;
declare function alert(message?: any): void;

declare class MyGlobalClass {
    constructor(name: string);
    greet(): string;
}

// Declaring a module
declare module 'lodash' {
    export function sortBy<T>(collection: T[], iteratees?: string | ((value: T) => any)): T[];
    export function identity<T>(value: T): T;
}

Declaration Files (`.d.ts`)

Ambient declarations are typically organized into declaration files, identifiable by the .d.ts file extension. These files contain no executable code; they are pure type definitions. When you install type packages (e.g., using npm install @types/react), you are installing .d.ts files that describe the API of that JavaScript library to TypeScript.

The TypeScript compiler automatically looks for .d.ts files in your project and in the node_modules/@types directory to gather type information. This allows you to write TypeScript code that uses, for example, the React library, and benefit from strong typing, even though React itself is written in JavaScript.

Key Characteristics

• Compile-Time Only: Ambient declarations have no runtime impact. They are entirely stripped out during compilation to JavaScript.
• Describe Existing Code: They define the type shape of code that already exists elsewhere, rather than creating new implementations.
• Enables Interoperability: Critical for integrating TypeScript with existing JavaScript libraries, frameworks, and browser APIs.
• declare Keyword: The central keyword used to denote ambient declarations.
• .d.ts Files: The standard location for organizing and distributing ambient declarations, especially for external libraries.