Declaration Files (.d.ts)

A .d.ts file describes the types of JavaScript values provided by another module, without defining their runtime implementation. Declaration files let TypeScript analyze JavaScript libraries and editor APIs. They must match the real module contract.

Reading the code: declare function describes a function but emits no JavaScript implementation. This runnable example does not call the declaration-only function; it converts "18" using an actual built-in Number function.

Keep the boundary clear: Never invoke a declaration-only function unless the corresponding JavaScript implementation is present; the compiler does not generate it.

Save the code as declaration-files-d-ts.ts. The result below was captured after compiling this exact example with strict TypeScript checking and executing the emitted JavaScript in Node.js.

TypeScript code

export declare function parseScore(text: string): number;
const example: { value: number } = { value: Number("18") };
console.log(example.value);

Verified output

18

Build: npx tsc --strict --target es2022 --module commonjs --lib es2022,dom,esnext.disposable declaration-files-d-ts.ts; run: node declaration-files-d-ts.js. The exact filename may be changed freely. When a multi-file project exists, prefer its tsconfig.json and build scripts.

declare function describes a function but emits no JavaScript implementation. This runnable example does not call the declaration-only function; it converts "18" using an actual built-in Number function.

The output shown above comes from the initialized values in this program. Replacing a type annotation alone does not transform a JavaScript value.

This separate mini-project demonstrates real imports, exports, or declarations across files. Create each file in one folder, then compile and run main.js. The example was checked separately from the single-file program.

helpers.js

exports.parseScore = text => Number(text);

helpers.d.ts

export declare function parseScore(text: string): number;

main.ts

import {parseScore} from "./helpers";console.log(parseScore("28"));

CommonJS setup: compile with npx tsc --strict --target es2022 --module commonjs main.ts and run node main.js. Compile from the same directory so relative modules are discovered. If this example contains helpers.js, keep that runtime file alongside the emitted main.js.

Verified output from the mini-project

28

Never invoke a declaration-only function unless the corresponding JavaScript implementation is present; the compiler does not generate it.

Check both the TypeScript diagnostic and the emitted JavaScript behavior. A program can compile correctly and still need runtime validation or error handling.

Write helpers.js containing a function and helpers.d.ts describing its parameter and return types; import it from a TypeScript consumer.

Before running your change, write down the type you expect TypeScript to infer and the output you expect JavaScript to print. Then check both predictions.

A .

Try the practice change and re-run the exact program to test your understanding.