Declaration Files: How TypeScript Knows Your Library's Shape

WHY IT EXISTS JavaScript is dynamically typed, but TypeScript is statically typed. To use the vast ecosystem of existing JavaScript libraries within a TypeScript project, developers need a way to describe the types of those libraries without rewriting them. Declaration files bridge this gap, allowing TypeScript to understand plain JavaScript.

THE MENTAL MODEL Think of a .d.ts file as a contract or an API reference manual for JavaScript code. It doesn't contain the machine's inner workings (the implementation), just the public-facing controls and what they expect (the types). It describes the "shape" of the JavaScript so the TypeScript compiler can validate your usage of it.

HOW IT WORKS TypeScript has two main file types. A .ts file contains both types and executable code and compiles to a .js file. In contrast, a .d.ts file is a declaration file that contains only type information. It declares the existence of types, variables, and functions without providing their implementation. For example, it might say declare function myLibraryFunc(arg: string): number; but won't include the function's body. The compiler reads these files to type-check your code but does not generate any JavaScript output from them.

WHEN TO USE IT You interact with declaration files constantly. First, TypeScript includes built-in .d.ts files (like lib.es2015.d.ts or lib.dom.d.ts) for standard JavaScript and browser APIs. Second, when you install a library like npm install @types/lodash, you're downloading a community-maintained declaration file for the Lodash library. Third, you might write your own .d.ts file to provide types for a legacy internal JavaScript library or a module that doesn't ship with its own types.

WHEN NOT TO USE IT Do not put any implementation logic in a .d.ts file. If you need to write executable code—like a function body, a class constructor's logic, or variable initializations—that code belongs in a .ts (or .tsx) file. A .d.ts file is strictly for describing types that exist elsewhere; any logic written inside will be ignored by the compiler.

ONE CANONICAL EXAMPLE When you write Math.max(1, 5), TypeScript knows this is valid. If you write Math.mix(1, 5), it throws an error. TypeScript has no knowledge of the Math object's source code. Instead, it consults a built-in declaration file, lib.es5.d.ts, which contains a line like interface Math { max(...values: number[]): number; }. This interface tells TypeScript that a max method exists on Math and what its signature is, but it says nothing about a mix method.