Ambient Module
In one line
Ambient modules (declare module) describe JS libraries' types without implementation — used in .d.ts files.
In simple words
An ambient module declaration tells TypeScript about a module that exists at runtime (usually a JS library) but has no TypeScript types. It's a type-only description — no implementation.
Syntax: declare module "library-name" { export function foo(): void; }
This is what .d.ts files contain — type declarations for JS libraries. DefinitelyTyped (@types/* packages) provides ambient declarations for thousands of libraries.
Without ambient declarations, importing a JS library gives you any types. With them, you get full type safety. You can also write your own ambient declarations for internal JS modules.
Example
// my-utils.d.ts — ambient declaration for a JS file
declare module "my-utils" {
export function format(date: Date): string;
export const VERSION: string;
export type Config = { debug: boolean };
}
// Now TypeScript knows the types
import { format, VERSION, Config } from "my-utils";
const s: string = format(new Date()); // Typed!
const v: string = VERSION; // Typed!declare module describes a JS module's types without implementation. This gives type safety when importing untyped JS libraries.
Common confusions
Confused with: module augmentation
The difference: An ambient module creates type declarations for a module that has no types at all. Module augmentation adds to a module that already has types. Ambient creates; augmentation extends. Use ambient for untyped JS, augmentation for typed libraries you want to extend.
Related terms
Related Resources
Related Lessons
- TypeScript Declarations
Ambient modules.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.