Why declaration files are needed in Typescript

Introduction

Declaration files tell TypeScript about code written in JavaScript or other libraries. They help TypeScript understand types and check errors before running the program.

When using a JavaScript library in a TypeScript project to get type information.

When sharing your TypeScript code with others without exposing the full source code.

When you want better code completion and error checking for external code.

When integrating third-party code that does not have built-in TypeScript support.

Syntax

Typescript

declare module 'module-name' {
  export function functionName(param: type): returnType;
  export const constantName: type;
}

Declaration files usually have a .d.ts extension.

They describe the shape of code but do not contain actual implementation.

Examples

This declares a module named 'math-lib' with a function add that takes two numbers and returns a number.

Typescript

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

This declares a constant VERSION of type string available globally.

Typescript

declare const VERSION: string;

Sample Program

The declaration file math-lib.d.ts tells TypeScript about the add function. This helps TypeScript check the types when we use add in main.ts.

Typescript

/* math-lib.d.ts */
declare module 'math-lib' {
  export function add(a: number, b: number): number;
}

/* main.ts */
import { add } from 'math-lib';

const result = add(5, 3);
console.log(`Result is ${result}`);

Important Notes

Declaration files improve developer experience by enabling autocomplete and error checking.

They do not generate any JavaScript code themselves.

You can find many declaration files for popular libraries on DefinitelyTyped.

Summary

Declaration files describe types for JavaScript code so TypeScript can understand it.

They help catch errors early and improve code completion.

They are especially useful when using external libraries without built-in TypeScript support.