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.
// math.d.ts export declare function add(a: number, b: number): number; export interface Options { precision?: number } export declare const version: string;
Try it
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.
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
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.tscannot contain statements or initialized code. Writingconst 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.tsit creates a new ambient module, as the first example shows: it stops withmain.ts(5,16): error TS2664: Invalid module name in augmentation, module 'virtual-module' cannot be found.- Type errors inside a
.d.tsare reported unlessskipLibCheckis on, which skips checking all declaration files. - If a
.d.tsand a.tsfile have the same base name, TypeScript prefers the.tsfile.
Usage notes
- Where they come from: next to the JavaScript (
index.jsandindex.d.ts), referenced by thetypesfield inpackage.json, inexportsunder thetypescondition, in@types/*packages from DefinitelyTyped, or generated bydeclaration: true. - Pick the right extension: with
nodenext,.d.mtsdescribes an ES module and.d.ctsa CommonJS module; a plain.d.tsfollows the packagetype. - Declarations are not checked against the code. If the
.d.tssays a function returns a number and it returns text, TypeScript cannot tell. Keep them in sync through tests such astsdorexpect-type. - Include the file: a
.d.tsis used only if the compiler reaches it, throughinclude,files, an import, or atypesreference. - Prefer generating declarations from TypeScript source over writing them by hand.
- See Writing a .d.ts file for a worked process.