TypeScript Declaration Files (.d.ts)
debt(d5/e3/b5/t5)
Closest to 'specialist tool catches it' (d5). The TypeScript compiler (tsc) surfaces missing declaration files as 'implicitly has type any' errors or by silently falling back to any — caught by tsc during build or type-checking, not by a default linter rule and not invisible in production, but requiring TypeScript tooling (tsc, dts-gen) to surface as listed in detection_hints.tools.
Closest to 'simple parameterised fix' (e3). The quick_fix is a targeted set of actions: install @types/packagename, add 'types' field in package.json, or run tsc --declaration. This is more than a single-line patch but does not span multiple files in a cross-cutting way — it's a focused fix per library dependency.
Closest to 'persistent productivity tax' (b5). Missing or mismatched declaration files affect every developer consuming a library — any time a new dependency is added or updated, the team must check for @types packages or maintain local .d.ts files. This applies broadly across web and cli contexts and recurs throughout the project lifecycle, slowing multiple work streams without being fully architectural.
Closest to 'notable trap' (t5). The misconception is explicitly documented: developers commonly assume all npm packages ship type declarations, but many older packages do not. This is a well-known gotcha in the TypeScript ecosystem (check DefinitelyTyped, add declare module fallbacks), but it is a documented and learnable surprise rather than a catastrophic or contradictory behaviour.
Also Known As
TL;DR
Explanation
Declaration files (.d.ts) contain only type declarations — no runtime code. Generated from TypeScript source with tsc --declaration. For JavaScript libraries: @types/* packages on DefinitelyTyped. Key declarations: declare module for untyped packages, declare global to augment global scope. tsconfig.json declaration: true generates .d.ts alongside .js for published libraries. Declaration merging: allows extending existing module types — used to add types to third-party modules.
Common Misconception
Why It Matters
Common Mistakes
- Not installing @types/* packages for common libraries — axios, lodash, express all need @types
- Manually writing declaration files for packages that already have them
- Not setting declaration: true in tsconfig for published libraries — consumers cannot use your types
- Duplicate type declarations when @types package exists
Code Examples
import moment from 'moment'; // No @types/moment installed
const date = moment('2026-01-01'); // date: any — all type safety lost
date.nonExistentMethod(); // No error — any accepts everything// Install declarations:
// npm install --save-dev @types/moment
import moment from 'moment';
const date = moment('2026-01-01'); // date: Moment — fully typed
date.nonExistentMethod(); // TypeScript error: property does not exist
// Custom declaration for untyped package:
// types/legacy.d.ts:
declare module 'legacy-lib' {
export function init(options: { debug: boolean }): void;
export function process(data: string): string;
}