What are Declaration Files (.d.ts) in TypeScript?
Understand TypeScript declaration files (.d.ts): how they add types to JavaScript libraries, what @types and DefinitelyTyped are, and how to write your own.
Expected Interview Answer
Declaration files (.d.ts) are TypeScript files that contain only type information — signatures, interfaces, and ambient declarations — with no implementation, telling the compiler the shape of code without generating any JavaScript.
They act as a type contract for JavaScript libraries so TypeScript can type-check and autocomplete against untyped code. The compiler can emit them automatically from your source when declaration is true, ship them in packages, or you can hand-write ambient declarations for global variables and untyped modules. The community publishes types for popular JS libraries under the @types/ namespace on DefinitelyTyped.
- Provide types for plain JavaScript libraries
- Enable IntelliSense, autocomplete, and safe refactoring
- Separate the type contract from the implementation
- Let library authors ship types without exposing source
- Catch integration errors at compile time
AI Mentor Explanation
A declaration file is like a team sheet handed to the umpires before play. It lists each player's role, batting order, and number, but contains none of the actual batting or bowling. The umpires know exactly who does what and can flag illegal moves, even though the sheet holds no play itself.
Step-by-Step Explanation
Step 1
Recognize the need
You import a JavaScript library that ships no types and lose type safety and autocomplete.
Step 2
Look for @types
Install community types via npm install --save-dev @types/library-name from DefinitelyTyped.
Step 3
Or write your own
Create a .d.ts file with declare module or ambient declarations describing the shapes you use.
Step 4
Emit from source
Set declaration: true in tsconfig so your own package emits .d.ts alongside its JavaScript.
Step 5
Reference and check
The compiler picks up declarations via types/typeRoots and type-checks all consumers.
What Interviewer Expects
- Understands .d.ts contains types only, no implementation
- Knows about @types and DefinitelyTyped
- Can explain the declaration compiler flag for emitting types
- Understands ambient declarations and declare module
- Knows why libraries ship type definitions
Common Mistakes
- Thinking .d.ts files contain runtime logic
- Not installing @types packages for untyped libraries
- Confusing declaration files with regular .ts modules
- Forgetting declaration: true when publishing a typed library
- Assuming a .d.ts emits JavaScript output
Best Answer (HR Friendly)
“A declaration file is a TypeScript file ending in .d.ts that describes the shape of code — its functions and types — without any actual logic. It lets TypeScript understand plain JavaScript libraries so you get autocomplete and error checking, which is why the community publishes @types packages.”
Code Example
// legacy-lib.d.ts
declare module 'legacy-lib' {
export interface Options {
retries: number
timeoutMs?: number
}
export function fetchData(url: string, opts?: Options): Promise<string>
export const version: string
}
// usage.ts
import { fetchData } from 'legacy-lib'
// Fully typed and autocompleted, even though legacy-lib is plain JS
fetchData('https://api.example.com', { retries: 3 })Follow-up Questions
- What is DefinitelyTyped and how do @types packages work?
- How do you enable emitting .d.ts files from your own source?
- What is the difference between declare module and declare global?
- How does the compiler resolve which declaration files to load?
- When would you write an ambient declaration versus installing @types?
MCQ Practice
1. What does a .d.ts file contain?
Declaration files hold type information only and emit no JavaScript of their own.
2. Where are community-maintained type definitions published?
DefinitelyTyped publishes types under the @types/ namespace on npm.
3. Which tsconfig option emits .d.ts files from your source?
Setting declaration: true makes the compiler generate .d.ts files alongside the emitted JavaScript.
Flash Cards
What is a .d.ts file? — A TypeScript declaration file containing type info only, with no implementation and no emitted JS.
What is DefinitelyTyped? — A community repo publishing types for JS libraries under the @types/ npm namespace.
How do you emit .d.ts from source? — Set declaration: true in tsconfig.json.
What is an ambient declaration? — A declare statement describing globals or untyped modules the compiler should trust.