Ambient Declarations & .d.ts Files

The plain-language idea

declare tells TypeScript "trust me, something with this shape exists at runtime — I'm not defining it here, just describing it." It's the type-space-only half of a declaration, with no accompanying implementation:

// global.d.ts
declare const __APP_VERSION__: string;   // injected by the build tool, not defined in any .ts file

// now usable anywhere in the project:
console.log(__APP_VERSION__);   // ✅ type-checks, even though it's never actually declared with const/let

A .d.ts file is a file containing only these kinds of declarations — no actual implementations, no runtime code, purely type information for something that exists (or will exist) elsewhere.

The most common real use: typing a plain JS library

// my-untyped-lib.d.ts
declare module "my-untyped-lib" {
  export function doThing(x: number): string;
}

import { doThing } from "my-untyped-lib";  // now type-checked, autocomplete works

Without this, importing a library with no types (and no @types/ package available) either errors or silently becomes any everywhere it's used — a hand-written .d.ts restores real type safety for code TypeScript can't see inside.

declare module 'legacy-lib' { export function doThing(x: number): void; } — describes shape without providing implementation.

BackNext

What people usually miss

Watch out

• declare produces zero runtime code. It's a promise to the compiler, not a definition — if the thing you declared doesn't actually exist at runtime (wrong global name, library not actually installed), you get a runtime error the type checker had no way to catch.
• @types/ packages on npm are just published .d.ts files for libraries that don't ship their own types — @types/lodash is exactly the same kind of file you'd hand-write for an internal untyped library, just maintained externally.
• Ambient declarations are global by default unless the file has at least one top-level import/export, which turns it into a module and scopes its declarations to explicit exports instead of leaking into the global namespace.

Why this matters in interviews

"How would you add TypeScript types for a JavaScript library that doesn't have any?" is a genuinely common real-world scenario, and writing a .d.ts file with declare module is the concrete, correct answer — showing you've actually worked in a mixed JS/TS codebase.