Declaration file syntax (.d.ts) in Typescript

Introduction

Declaration files tell TypeScript about the shape of code written in JavaScript or other files. They help TypeScript understand what types and functions exist without running the code.

You want to use a JavaScript library in a TypeScript project and need type information.

You write a library in JavaScript but want to provide type info for users.

You want to separate type definitions from implementation for clarity.

You want to describe global variables or modules that TypeScript doesn't know about.

You want to avoid rewriting existing JavaScript code but still get type checking.

Syntax

Typescript

declare module 'module-name' {
  export function functionName(param: type): returnType;
  export interface InterfaceName {
    property: type;
  }
  // other declarations
}

declare const variableName: type;

declare function functionName(param: type): returnType;

interface InterfaceName {
  property: type;
}

// No implementation code, only declarations

Declaration files use the declare keyword to tell TypeScript about existing code without implementing it.

They only describe types, interfaces, variables, and functions, but never contain actual code logic.

Examples

This declares a module named 'math-lib' with two functions, add and subtract, both taking two numbers and returning a number.

Typescript

declare module 'math-lib' {
  export function add(a: number, b: number): number;
  export function subtract(a: number, b: number): number;
}

This declares a constant named VERSION of type string available globally.

Typescript

declare const VERSION: string;

This declares an interface User describing an object with three properties.

Typescript

interface User {
  id: number;
  name: string;
  isActive: boolean;
}

This declares a function greet that takes a string and returns nothing (void).

Typescript

declare function greet(name: string): void;

Sample Program

This example shows a declaration file math-lib.d.ts describing a module with a function and a constant. The usage file imports them and uses them to calculate and print the area of a circle.

Typescript

/* math-lib.d.ts */
declare module 'math-lib' {
  export function multiply(x: number, y: number): number;
  export const PI: number;
}

/* usage.ts */
import { multiply, PI } from 'math-lib';

const area = multiply(PI, 5 * 5);
console.log(`Area of circle: ${area}`);

Important Notes

Declaration files do not contain real code, so running the sample program without the actual module will print NaN because multiply and PI are not implemented.

Declaration files help TypeScript check your code but do not create JavaScript output themselves.

Summary

Declaration files (.d.ts) describe the shape of existing code for TypeScript.

They use declare to define types, functions, variables, and modules without implementation.

They help TypeScript understand JavaScript libraries and improve code safety.