Declaration files

What it is and why it exists

A declaration file is the static shape of a JavaScript API. It records the functions, classes, constants, and types exported by a module, or the global names supplied by a host. TypeScript reads this information while checking consumers but does not turn declarations into values when it emits JavaScript; this is type erasure .

That boundary matters. declare function charge(): Receipt means “this function exists elsewhere at runtime,” not “generate this function.” A declaration can give the editor and compiler an accurate view of an API. A wrong declaration can also give an entire project false confidence.

You meet declarations in three common places. A JavaScript package can bundle its own types, an @types package can cover a package without built-in types, and an application can keep local declarations for host-injected globals or non-code resources. If a library is already written in TypeScript, you should usually generate its public declarations instead of maintaining a second handwritten API.

Declaration files do not validate network responses, configuration files, or arbitrary JavaScript values. External data should still enter as unknown, pass runtime validation, and only then receive a domain type. Declarations answer “how does the checker understand this existing API?”, not “is this runtime value trustworthy?”

As a consumer, your job is to find declarations that match the dependency version and confirm what resolution selected. As a library author, your job is to publish a contract reachable through consumer paths and consistent with every runtime entry point.

How it works

TypeScript works with two related graphs: the runtime module graph decides what JavaScript loads, while the type graph decides what the checker sees. A declaration file belongs to the type graph but must faithfully describe the runtime graph. A mismatch in export names, default exports, calling conventions, or module format can make checked code fail when it loads or calls the API.

Both paths in the diagram must meet at the consumer. The checker finding formatInvoice does not prove that the runtime loader can get that name from the same module. Test declarations with tsc and at least one real import.

The boundary between declarations and implementations

An ambient declaration tells the checker that another piece of code supplies an entity. A variable after declare cannot have a normal initializer, and a declared function cannot have a body; either would cross the “describe, don’t implement” boundary. Top-level declarations in a .d.ts file are already in an ambient context, so many positions do not need another declare modifier.

A declaration should describe the public surface that consumers can observe, not copy implementation details. Unexported helpers, cache layouts, and private locals are not part of the contract. Whether a returned object is readonly, an argument is optional, or a function can return undefined does change how callers use the API and must be represented accurately.

The types cannot be more precise than the runtime facts. If JavaScript accepts a string or a number, the declaration cannot claim it accepts only strings; if lookup can fail, the return type cannot omit undefined. A broad any loses errors, while a signature that is too narrow rejects valid calls. Both are declaration bugs.

Scripts, modules, and global scope

If a declaration file has no top-level import or export, its top-level names enter global scope. That fits a legacy API genuinely installed by a script tag or host, but it can pollute every file in an application. Modern packages should normally use module declaration files and export public members explicitly at the top level.

Any top-level import or export makes the file a module. To add a global name from a module file, use export {} to establish the module boundary, then put the addition inside declare global {}. The structure makes intentional global changes visible.

The string form declare module "package-name" can describe an external module that has no types. Similar syntax inside a file that already resolves a module can perform module augmentation; augmentation extends an existing declaration and cannot replace a default export or create a runtime member. The related topic covers the full augmentation rules.

Declaration merging applies only to declaration kinds that permit it. Two interface declarations with the same name in one scope can merge members, but type aliases do not. Do not assemble a package API through accidental global merging; keep file and module ownership explicit.

How the compiler finds declarations

For a relative import, TypeScript follows the host lookup modeled by the active moduleResolution mode, then uses extension substitution to look for a .ts file or the corresponding declaration. If the runtime target is ./invoice-tools.js, for example, the checker can read invoice-tools.d.ts next to it. This does not rewrite the module specifier sent to the runtime.

For a package import, package.json fields such as exports and types, the module format, and the resolution mode all affect the result. When exports is not being read, types provides an explicit declaration entry for the package root. When exports is present, each public subpath should also map to types that agree with its runtime target. A root index.d.ts is not enough if exported subpaths have been omitted.

Visible packages under node_modules/@types can supply global types and package declarations. compilerOptions.types limits which @types packages enter global scope, while typeRoots changes the directories treated as type package roots; neither is a general-purpose path alias. When resolution is unclear, use tsc --traceResolution to inspect actual candidates instead of guessing from a fixed list.

Successful resolution only proves that the checker found a declaration. It does not prove that the declaration matches the current JavaScript version or that the runtime can load the same entry. Package upgrades, conditional exports, and dual ESM/CommonJS releases need contract tests.

Examples

The next four examples follow one workflow: add types to an existing JavaScript module, declare a real host global, generate declarations from TypeScript source, and prevent contract drift with type tests. The implementation and declaration files belong to one small example workspace.

Handwriting types for a JavaScript module

The legacy module already exports currency and formatInvoice at runtime. Its implementation remains JavaScript; the declaration file records only the shape visible to callers.

The declaration and JavaScript use exactly the same export names, and the consumer keeps the .js module specifier. Invoice exists only in the type layer, so import type says so directly. currency is a runtime value and cannot be imported as a type only.

The literal type "EUR" comes from a real constant, not the declaration author’s wish. If the implementation later allows configurable currencies, the declaration needs a wider type. Conversely, adding a function to the declaration does not make JavaScript export it at runtime.

Declaring a host-provided global

Some build systems provide build information before an application starts. A local declaration teaches application code its shape, but the example still installs the runtime value explicitly so the declaration cannot be mistaken for an implementation.

export {};

declare global {
  var BUILD_INFO: Readonly<{
    version: string;
    channel: "stable" | "canary";
    builtAt: string;
  }>;
}

/// <reference path="./globals.d.ts" />

globalThis.BUILD_INFO = Object.freeze({
  version: "6.2.0",
  channel: "stable",
  builtAt: "2026-09-04T08:30:00Z",
});

const label = `${BUILD_INFO.version} (${BUILD_INFO.channel})`;
console.log(label);
console.log(BUILD_INFO.builtAt);

6.2.0 (stable)
2026-09-04T08:30:00Z

export {} stops helper names other than Readonly from leaking into global scope, while declare global explicitly opens the part being extended. This example uses var because a global var declaration corresponds to a property on globalThis; that is not a recommendation to introduce mutable global state throughout an application.

Test environments, server rendering, and command-line scripts must install the same value or check for it during startup. The declaration cannot replace that work. If the data can come from an ordinary module import, a module is usually easier to trace and test than a global name.

Generating declarations from typed source

When library source is already TypeScript, compiler output avoids a second handwritten API. This module has a public interface, constant, and function; first run the behavior, then inspect declaration output separately.

export interface InventoryItem {
  readonly sku: string;
  readonly available: number;
}

export const inventoryVersion = 3 as const;

export function stockLabel(item: InventoryItem): string {
  const state = item.available > 0 ? "in stock" : "back order";
  return `${item.sku}: ${state}`;
}

const sample: InventoryItem = {
  sku: "KB-87",
  available: 12,
};

console.log(stockLabel(sample));

KB-87: in stock

npx tsc inventory.ts \
  --declaration --emitDeclarationOnly \
  --module nodenext --moduleResolution nodenext \
  --target es2022 --outDir dist
sed -n '1,80p' dist/inventory.d.ts

export interface InventoryItem {
    readonly sku: string;
    readonly available: number;
}
export declare const inventoryVersion: 3;
export declare function stockLabel(item: InventoryItem): string;

declaration enables declaration emit , while emitDeclarationOnly suppresses JavaScript output. This pair fits a build where another tool transpiles JavaScript; it is wrong if tsc is also responsible for producing the runtime code.

The generated file keeps public signatures and drops the function body and sample call. inventoryVersion retains the literal 3 because as const fixes the public value in source. Before each release, check that the generated artifact enters the package; a declaration generated locally can still be excluded by .gitignore or a package file allowlist.

Locking the contract with type tests

Runtime tests prove JavaScript behavior for a few inputs. Type tests must also prove that valid calls are accepted and invalid calls are rejected. @ts-expect-error is better than @ts-ignore for negative cases because the test fails if the expected diagnostic disappears.

import {
  formatInvoice,
  type Invoice,
} from "./invoice-tools.js";

const valid: Invoice = { id: "INV-105", total: 21.5 };

if (false) {
  // @ts-expect-error total must be a number.
  formatInvoice({ id: "INV-106", total: "21.5" });

  // @ts-expect-error id is required.
  formatInvoice({ total: 21.5 });
}

console.log(formatInvoice(valid));

INV-105: EUR 21.50

Run this file through tsc --noEmit before executing its success path. Running only with tsx is insufficient because it transpiles and executes the file without replacing full type checking. Tests should also import from the installed package entry instead of bypassing exports and reaching into source.

Negative cases should represent the real contract, not arbitrary mistakes added to inflate a count. If a package supports several subpaths or two module formats, every public entry needs at least one successful import. Overloads, generic inference, and optional properties that often drift need focused cases of their own.

Pitfalls

A handwritten .d.ts does not stay synchronized with JavaScript. Fix: Generate it from published source when possible. If it must be handwritten, run real import tests and compare return values, errors, optional members, and asynchronous behavior with the implementation.

The bug can pass quietly in one project and produce duplicate or widened members under another dependency set. Fix: Give module declarations a top-level export. For an intentional global addition, use export {} with declare global, and keep the added surface small.

A shim can be a very short migration seam, but it is not a publishable contract. Fix: Start with precise signatures for the smallest API actually used, keep uncertain data as unknown, and add members as coverage grows. Do not claim that unchecked API surface has types.

The option skips full checking inside declaration files and is commonly used to cope with duplicated or inconsistent dependency types. It does not compare declarations with JavaScript. Fix: Check your library’s declarations and type tests separately, and track the upstream issue being skipped instead of replacing a fix with one global switch.

The editor may accept a named import that gives Node only a default value, or a typed exports subpath may be unreachable at runtime. Fix: Test ESM and CommonJS entries from a temporary installation of the packed artifact. Match .d.mts, .d.cts, or package-typed .d.ts files to the corresponding JavaScript format.

Further reading

• TypeScript Handbook: declaration files introduction
• TypeScript Handbook: module declaration template
• TypeScript Handbook: global declaration template
• TypeScript Handbook: module resolution reference
• TypeScript TSConfig: declaration