Advanced TypeScript

Declaration Files & Ambient Types

Declaration files describe the types of JavaScript code to TypeScript. Ambient declarations tell TypeScript about values, globals, or modules that exist at runtime but are not defined in the current TypeScript source.

.d.ts files contain types only
Declarations can type JavaScript libraries
declare means 'trust me, this exists at runtime'
Module declarations bridge untyped packages
Bad declarations create confident bugs

Ambient module declaration

declare module "legacy-parser" {
  export function parse(input: string): unknown
}

declare const __APP_VERSION__: string

These declarations tell TypeScript about runtime values supplied elsewhere.

Declaration concepts
Concept	Meaning	Example
.d.ts	Type declarations	index.d.ts
declare module	Describe external module	legacy package
declare global	Augment global scope	window flags
@types package	Community declarations	@types/node
types field	Package declaration entry	package.json