Understanding .d.ts Declaration Files in TypeScript

By the end of this page, you will understand what .d.ts files are, how they differ from .ts and .js files, and when each file type is needed. You will also learn how TypeScript connects declaration files to JavaScript modules and why .d.ts files describe code rather than implement it.

What a .d.ts file is

A .d.ts file is a TypeScript declaration file. Its job is to describe the shape of code without containing the actual implementation.

That means a declaration file can say:

• a function exists
• what parameters it accepts
• what it returns
• what objects, classes, or constants are available

But it does not contain the executable logic.

The role of each file type

.ts

A .ts file contains TypeScript source code.

• It can contain implementation
• It can contain types
• It is usually compiled into .js

Example:

export function add(a: number, b: number): number {
  return a + b;
}

.js

A .js file contains .

Think of these files like a product in a box:

• .js is the actual product you can use
• .ts is the product being designed with detailed instructions
• .d.ts is the label on the box describing what is inside

The label is useful, but the label is not the product.

Another way to think about it:

• .js = the working machine
• .d.ts = the blueprint of the machine's public controls
• .ts = the original source used to build the machine

A blueprint can describe a machine, but it cannot run by itself.

Basic declaration syntax

A declaration file uses declarations instead of implementations.

Function declaration

export declare function greet(name: string): string;

This says:

• there is a function called greet
• it takes a string
• it returns a string

But there is no function body.

Variable declaration

export declare const version: string;

Interface declaration

export interface User {
  id: number;
  name: string;
}

Class declaration

Example

Suppose you have these files:

logger.js

export function log(message) {
  return `[LOG] ${message}`;
}

logger.d.ts

export declare function log(message: string): string;

main.ts

import { log } from './logger';

const result = log('Hello');
console.log(result);

What happens step by step

1. TypeScript reads main.ts

It sees:

1. Adding types to a JavaScript library

Many libraries are written in JavaScript but still want to support TypeScript users. A .d.ts file lets the library provide type information without rewriting the whole codebase in TypeScript.

2. Publishing a TypeScript package

A package author writes .ts source files and publishes:

• compiled .js
• generated .d.ts

Consumers get both runtime code and type safety.

3. Typing legacy code

In older projects, teams often have lots of JavaScript already. They can gradually add .d.ts files to describe existing modules and improve editor support before fully migrating to TypeScript.

4. Describing browser globals or external APIs

Declaration files can describe values that exist at runtime but are not defined directly in your current source, such as:

• global variables injected by a script
• APIs provided by a host environment
• third-party plugins

5. Internal shared contracts in large codebases

Teams may use declarations to describe public APIs between packages, especially in monorepos or shared libraries.

Common patterns in real projects

Generate .d.ts from .ts

This is the most common pattern in TypeScript libraries. Developers write normal TypeScript, then let the compiler generate declarations.

Benefits:

• avoids duplicating types manually
• keeps declarations in sync with implementation
• reduces mistakes

Write .d.ts manually for JavaScript code

This is common when:

• a project is still mostly JavaScript
• only type hints are needed
• migration to TypeScript is gradual

Describe package public APIs

Many packages expose only selected functions and classes. Their declaration files describe the exported API clearly, which acts like documentation and type safety at the same time.

Use declarations for globals

Example:

declare const API_URL: string;

This is useful when a bundler, environment, or script injects something at runtime.

Validation and contract clarity

Developers use type declarations to make function usage clearer:

export   {
  : ;
  : ;
}

   (): ;

1. Putting implementation code inside .d.ts

A declaration file should not contain real executable logic.

Incorrect

export function add(a: number, b: number): number {
  return a + b;
}

Correct

export declare function add(a: number, b: number): number;

2. Thinking .d.ts can run by itself

A .d.ts file is not runtime code. If you only keep a declaration file and remove the actual JavaScript or compiled output, there is nothing to execute.

3. Letting declarations get out of sync with implementation

math.js

  () {
   (a + b);
}

.ts vs .js vs .d.ts

.d.ts vs C/C++ header files

Quick reference

What each file does

• .ts = TypeScript source
• .js = runtime JavaScript
• .d.ts = type declarations only

Core rule

A .d.ts file describes code. It does not implement code.

Common file relationships

source.ts -> output.js + output.d.ts

or

library.js + library.d.ts

Declaration examples

export declare function greet(name: string): string;
export declare const version: string;

export interface User {
  : ;
  : ;
}

What is a .d.ts file in TypeScript?

A .d.ts file is a declaration file that describes the types and exported API of code without containing the actual implementation.

Do I need both .ts and .d.ts files?

Not always. If you write TypeScript, your .ts files may be enough during development, and .d.ts files can be generated when needed. If you write JavaScript, you may add .d.ts files manually.

Can a .d.ts file replace a .ts file?

No, not as implementation. A .d.ts file only provides type information. You still need JavaScript or compiled TypeScript code to run the program.

How does TypeScript match a .d.ts file to a .js file?

Usually through the same module name or file path. For example, importing ./math lets TypeScript use math.d.ts for types and math.js at runtime.

Are .d.ts files only for libraries?

• TypeScript modules — .d.ts files often describe the exports of modules.
• Type declarations — declaration files are built from function, class, interface, and variable type declarations.
• Interfaces in TypeScript — interfaces are commonly used inside .d.ts files to describe object shapes.
• Ambient declarations — these are declarations for values that exist elsewhere at runtime.
• TypeScript compiler (tsc) — it can generate .d.ts files from .ts source.
• Module resolution — this explains how TypeScript finds matching .d.ts and .js files.
• JavaScript interoperability — .d.ts files are a major tool for using JavaScript code safely from TypeScript.