Using Declaration Files for Unconverted Modules
You'll learn how to create .d.ts files that provide TypeScript with type information for JavaScript modules you haven't converted yet, giving you IDE support and type safety at the boundaries.
The Bridge Between Worlds
When you're migrating a large codebase incrementally, you'll have JavaScript files that won't be converted to TypeScript for weeks or months. But you still want autocomplete, type checking, and documentation when other TypeScript files import from them. Declaration files are your bridge—they tell TypeScript what shapes exist in your JavaScript modules without requiring you to rewrite those modules yet.
Think of it like putting up signs and maps around an old building you haven't renovated yet. The building still functions as-is, but now everyone knows where the exits are and what's in each room.
Why This Matters During Migration
Without declaration files, importing from unconverted JavaScript modules gives you any types everywhere—you lose all type safety at those boundaries. By writing .d.ts files, you:
- Get autocomplete when importing from JS modules
- Catch type errors when calling JS functions from TS code
- Document what the JS module actually exports
- Make your TypeScript files fully type-safe even when dependencies are still JS
Writing Your First Declaration File
For a JavaScript file utils.js that you haven't converted:
// utils.d.ts - the declaration file
export function formatName(first: string, last: string): string;
export function calculateTotal(items: Array<{ price: number }>): number;
export const MAX_RETRIES: number;
This declares the shape of what utils.js exports without changing the JavaScript file itself. Now TypeScript knows what to expect when other files import from utils.js.
Matching Your JavaScript's Real Shape
The key is accurately describing what the JavaScript module actually does. If your JS file exports an object with methods:
// api-client.d.ts
interface ApiClient {
get(url: string): Promise<unknown>;
post(url: string, data: unknown): Promise<unknown>;
}
declare const client: ApiClient;
export default client;
This matches a JavaScript module that does export default { get: ..., post: ... }.
Where Declaration Files Go
Place the .d.ts file right next to the .js file it describes—utils.js and utils.d.ts in the same directory. TypeScript automatically finds and uses the declaration file when you import the JavaScript module.
Progressive Refinement
Start with loose types like unknown or basic shapes, then tighten them as you learn more:
// parser.d.ts - first pass
export function parse(input: string): unknown;
// Later, when you understand the return shape better:
export function parse(input: string): { id: string; data: Record<string, unknown> };
You're documenting what you know now, and you can improve it before or during the actual conversion.
Key Takeaway: Declaration files let you add type information to JavaScript modules you haven't converted yet, maintaining type safety at module boundaries and enabling full IDE support without rewriting code—essential for smooth incremental migrations.