.d.ts files: ambient declarations, augmentation, and the public type surface

declare: shapes without implementations

A .d.ts file contains only type information — no executable code is allowed, so everything is declared. This is how you describe a value that exists at runtime but that TypeScript can’t see (a global from a script tag, an untyped npm package):

// globals.d.ts — ambient declarations (no import/export = a SCRIPT, global scope)
declare const __APP_VERSION__: string;     // injected by the bundler at build time
declare function gtag(...args: unknown[]): void;

interface Window {                          // merges into the built-in Window
  dataLayer: unknown[];
}

A file with no top-level import/export is a script: its declarations are global. A file with any top-level import/export is a module: its declarations are local unless you wrap them in declare global. This module-vs-script distinction is the root of most augmentation failures.

Ambient modules: typing an untyped dependency

When you import a JS package that ships no types and has no @types/..., TypeScript errors TS7016. declare module "name" invents an ambient module declaration to fill the gap:

// shims.d.ts
declare module "legacy-chart" {
  export interface ChartOptions { width: number; height: number }
  export function render(el: HTMLElement, opts: ChartOptions): void;
  const _default: { version: string };
  export default _default;
}

A wildcard form types whole classes of imports — e.g. asset imports under a bundler:

declare module "*.svg" {
  const url: string;     // a Vite/webpack loader turns the file into a URL string
  export default url;
}

Module augmentation: extending someone else’s types

To add to a type that another module exports, re-open that module with declare module from inside your own module (the file must have its own import/export):

// augment.ts — has imports, so it's a MODULE
import "express"; // ensure the target module is loaded
declare module "express-serve-static-core" {
  interface Request { user?: { id: string; roles: string[] } } // merges into Express's Request
}
export {}; // belt-and-braces: guarantees module context

For global types (Window, Array, globalThis), you must wrap the augmentation in declare global — and the enclosing file must still be a module:

// env.d.ts
export {}; // makes this a module so `declare global` is legal here
declare global {
  interface Window { __APP_VERSION__: string }
  namespace NodeJS { interface ProcessEnv { DATABASE_URL: string } }
}

Emitting and shipping types

When you publish a library, the .d.ts files you ship are your API contract for every consumer’s editor and type checker. Get the emit wrong and consumers will see TS4023 errors or broken “go to definition” — even when your runtime is fine.

declaration: true makes tsc emit a .d.ts next to each .js. declarationMap: true emits a .d.ts.map so a consumer’s “go to definition” jumps to your real source, not the generated .d.ts. In package.json you point consumers at them via types (or the types condition in exports):

{
  "types": "./dist/index.d.ts",
  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } }
}

typeRoots/types (compiler options, distinct from the package.json field) control which @types packages are included: types: [] disables auto-inclusion of every @types/* in node_modules, which is a common fix for “a global from some transitive @types polluted my project”.

export type vs export

In a .d.ts you author by hand, prefer export type { Foo } for type-only exports so consumers (and single-file transpilers) know it carries no runtime value. A plain export { Foo } where Foo is a type works for type consumers but is ambiguous to tools that erase types per-file.