What are declaration files and when do you write one?

A declaration file contains type information only. It tells the compiler what a module or global value looks like so imports and calls can be checked. Declaration files are generated automatically when a TypeScript package is compiled, but you write them by hand for untyped JavaScript packages or global scripts.

export {};

declare module "legacy-widget" {
  export function mount(element: HTMLElement): void;
  export function unmount(): void;
}

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

Where declarations come from

• The package itself may ship .d.ts files
• The DefinitelyTyped project publishes @types packages
• You can write an ambient declaration for an internal or untyped module
• tsconfig types and typeRoots control which global declarations are included
• Module augmentation extends an existing package's types without forking it

A declaration must match the runtime behavior. If the declaration says a function returns a string but the implementation returns undefined, the compiler will happily allow code that crashes. Keep hand-written declarations small and cover only the API you actually use.