Basic Declaration File Structure
What you'll learn: You'll understand that declaration files contain only type information—no executable code—serving as pure type blueprints for TypeScript.
The Core Idea
A declaration file (.d.ts) is TypeScript's way of describing shapes without implementing anything. Think of it like an architectural blueprint: it shows where the doors and windows are, but you can't actually walk through the door. The blueprint describes the structure; the actual building exists elsewhere.
Declaration files contain:
- Interfaces describing object shapes
- Type aliases defining type synonyms
- Function signatures showing parameters and return types
- Variable declarations specifying what type something is
They never contain:
- Function implementations with actual code
- Variable assignments or calculations
- Class method bodies
- Any executable JavaScript
Why This Separation Matters
When TypeScript compiles your code, it strips away all type information. Declaration files preserve that stripped information as a separate artifact. This lets you:
- Share type definitions for JavaScript libraries
- Describe existing runtime code without modifying it
- Keep types separate from implementation details
The declare keyword you've seen signals "this thing exists at runtime somewhere else—I'm just describing its type here."
Example Structure
While you haven't learned all declaration syntax yet, a declaration file might look like:
// Describes what exists, not how it works
declare function greet(name: string): void;
declare const version: string;
Notice: no = ..., no { } with code—just type signatures.
Key Takeaway: Declaration files are pure type information with zero runtime code—they're TypeScript's "shapes only" files that describe what exists elsewhere.