Skip to content

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

typescript
// 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

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary