Declaration Files (.d.ts)
Describe JavaScript libraries with .d.ts declaration files and the declare keyword.
What you'll learn
- What .d.ts files are and why they contain no implementation
- Using the declare keyword for ambient declarations
- How @types packages provide types for JS libraries
- Writing custom declarations for untyped modules
Concept
Ambient Declarations
A declaration file (.d.ts) contains type declarations only — no runtime code. It describes the types of an existing JavaScript library so TypeScript can type-check code that uses it. The declare keyword tells the compiler "this exists at runtime, trust me" without generating any JavaScript. For example, declare const VERSION: string; tells TypeScript a global VERSION constant exists without emitting code for it.
@types Packages
Most popular JavaScript libraries have community-maintained type definitions published as @types/library packages on npm (via the DefinitelyTyped repository). You install them with npm install --save-dev @types/lodash and TypeScript automatically finds them. If a library ships its own types (look for a types or typings field in package.json), you do not need a separate @types package.
Writing Custom Declarations
When a library has no types and no @types package, you can write a custom declaration. Create a .d.ts file and declare the module: declare module "my-lib" { export function doSomething(x: string): number; }. For global variables, use declare global { interface Window { myVar: string; } }. Custom declarations bridge the gap between typed TypeScript code and untyped JavaScript libraries.
Example
// --- globals.d.ts — ambient declarations (no runtime code) ---
// Declare a global variable that exists at runtime.
declare const APP_VERSION: string;
// Declare a global function.
declare function legacyFormat(date: Date): string;
// Augment the Window interface with a custom property.
declare global {
interface Window {
myAnalytics: (event: string) => void;
}
}
// Declare an untyped module.
declare module "legacy-lib" {
export function parse(input: string): Record<string, unknown>;
export const version: string;
}
// --- main.ts — using the declarations ---
// These exist at runtime (injected by a script tag or the environment).
console.log(APP_VERSION);
console.log(legacyFormat(new Date()));
window.myAnalytics("page_view");
// import { parse } from "legacy-lib";
// const data = parse('{"x":1}');
Declaration files (.d.ts) describe types without implementation. The declare keyword asserts runtime existence. @types packages provide types for JS libraries. Custom declarations handle untyped modules and global variables.
Try it
- JSON to TypeScript
Generated interfaces can serve as the basis for declaration files.
- Code Minifier
Declaration files compile to nothing — observe the empty output.
Common mistakes
The mistake
Putting runtime code in a .d.ts declaration file
The fix
Declaration files contain types only — no implementations. If you need runtime code, use a regular .ts file. The compiler does not emit JavaScript from .d.ts files.
The mistake
Not installing @types packages for JavaScript dependencies
The fix
Check if a @types/package exists for every JS library you use. Without it, the library is typed as any, losing all type safety for that dependency.
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.