Modules, declaration files and declaration merging

Declaration files

A .d.ts file holds types only: signatures, interfaces, declared values, and no implementations. It describes JavaScript that exists somewhere else — a compiled library, a global a script tag provides, a package written in plain JavaScript.

// analytics.d.ts
declare function track(event: string, props?: Record<string, unknown>): void;

declare module "legacy-pdf" {           // types for an untyped package
  export function render(html: string): Promise<Uint8Array>;
}

For a package, TypeScript finds the types in the package itself (its package.json types field or a types condition in exports), or in a separate @types/<name> package from DefinitelyTyped. tsc writes .d.ts files for your own code when declaration is on — that is how a TypeScript library ships its types to JavaScript consumers.

Type-only imports disappear

Types are erased, so an import used only for types has nothing to import at runtime. import type makes that explicit and guarantees the import is removed. In the example the module does not even exist, and the code runs:

1// This module does not exist. A type-only import is erased completely,2// so nothing tries to load it at runtime.3import type { Invoice } from "./no-such-module";4 5export function run(): string {6  const draft: Partial<Invoice> = {};7  return `ran fine with ${Object.keys(draft).length} keys`;8}

A plain import { thing } from "./no-such-module" used as a value fails in this sandbox with Cannot find module './no-such-module' before any code runs. Under the verbatimModuleSyntax setting, imports without type are kept exactly as written, so marking type-only imports becomes mandatory.

Without that setting, the compiler elides on its own: an imported name the file uses only as a type is dropped, and a declaration with no name left is removed entirely — taking any side effect of that module with it. A bare import "./polyfills"; names nothing and is always kept.

How an import is resolved

moduleResolution decides how import "x" becomes a file:

• node16 / nodenext — Node's own rules. In ES modules a relative import needs its extension, written as .js even though the source file is .ts (the import names the file that will exist after compiling). package.json exports is honoured.
• bundler — for code that a bundler processes: exports is honoured, but extensionless relative imports are allowed.
• node10 (formerly node) — the old CommonJS rules; ignores .

1// A function and a namespace with the same name merge into one value:2// a callable function that also carries properties.3function price(amount: number): string {4  return `${amount.toFixed(2)} ${price.currency}`;5}6 7namespace price {8  export const currency = "GEL";9  export function free(): string {10    return price(0);11  }12}13 14// Two interface declarations merge into one shape.15interface Settings {16  theme: string;17}18interface Settings {19  fontSize: number;20}21 22export function run(): unknown[] {23  const s: Settings = { theme: "dark", fontSize: 14 };   // both halves required24  return [price(12.5), price.free(), typeof price, Object.keys(price), s];25}

Merging is how you extend types you do not own. Module augmentation adds to an interface inside a package, and declare global adds to a global one (both must sit in a file that is itself a module):

export {};
declare global {
  interface Window { analytics: { track(event: string): void } }
}

Common mistakes

• Re-exporting a type as if it were a value. export { User } from "./types", where User is only an interface: a compiler that sees one file at a time cannot tell, and emits a re-export of a name that does not exist at runtime. isolatedModules reports it; export type { User } fixes it.
• Extensionless relative imports under nodenext. In ES modules Node requires the extension; write ./util.js in the .ts source.
• types listed after import in exports. The import condition matches first, so TypeScript uses whatever declaration sits beside the JavaScript file (possibly a stale or wrong one) and reaches types only when there is none.
• Hand-written that drifts. A declaration file is a promise about JavaScript nobody type-checks against it; generate it from source when you can.