Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Modules and Declaration Files

Declaration files (.d.ts)

What a .d.ts declaration file is: types without code, how the compiler finds them, what they may contain, how they differ from .ts files, and how to use them.

A declaration file has the extension .d.ts (or .d.mts, .d.cts) and contains only type information, with no executable code. It tells the compiler what a JavaScript file or global looks like: which functions exist, what they accept and return, and which classes and constants a module exports. Editors use the same file for autocomplete and hover documentation.

Declaration files are how TypeScript works with the JavaScript ecosystem. A library written in JavaScript ships (or is given) a .d.ts next to its code. A library written in TypeScript has its .d.ts generated for consumers, so they get types without needing the original source. Every declaration inside is either a type (interface, alias) or a declared value, which promises that something exists at run time without creating it.

TypeScript
// math.d.ts
export declare function add(a: number, b: number): number;
export interface Options { precision?: number }
export declare const version: string;

Try it

TypeScript Ambient module declarations belong in .d.ts (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript What a declaration promises about JavaScript

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
declare const name: Type;
declare function f(x: number): string;
declare class C { constructor(x: number); method(): void }
declare namespace NS { function g(): void }
declare module "pkg" { export const x: number }
declare global { interface Window { app: App } }
export {};   // makes the file a module
Rule Description
No implementations Functions have signatures without bodies, classes have member signatures, variables have types but no initializers (except const literal types).
declare Required for top-level values in a script-style .d.ts. In a module .d.ts, export declarations are already ambient.
Top-level import/export Makes the file a module. Without it, everything is global.
export = and export default Allowed, to describe CommonJS or default exports.

Edge cases and errors:

  • A .d.ts cannot contain statements or initialized code. Writing const x = compute() is an error.
  • declare module "x" in a file that has imports or exports is an augmentation and must name a module that exists (TS2664); in a script-style .d.ts it creates a new ambient module, as the first example shows: it stops with main.ts(5,16): error TS2664: Invalid module name in augmentation, module 'virtual-module' cannot be found.
  • Type errors inside a .d.ts are reported unless skipLibCheck is on, which skips checking all declaration files.
  • If a .d.ts and a .ts file have the same base name, TypeScript prefers the .ts file.

Usage notes

  • Where they come from: next to the JavaScript (index.js and index.d.ts), referenced by the types field in package.json, in exports under the types condition, in @types/* packages from DefinitelyTyped, or generated by declaration: true.
  • Pick the right extension: with nodenext, .d.mts describes an ES module and .d.cts a CommonJS module; a plain .d.ts follows the package type.
  • Declarations are not checked against the code. If the .d.ts says a function returns a number and it returns text, TypeScript cannot tell. Keep them in sync through tests such as tsd or expect-type.
  • Include the file: a .d.ts is used only if the compiler reaches it, through include, files, an import, or a types reference.
  • Prefer generating declarations from TypeScript source over writing them by hand.
  • See Writing a .d.ts file for a worked process.