Glossary / Type declarations

Type declarations

Type declarations describe the static shape of JavaScript code to TypeScript without necessarily providing runtime implementation. Declaration files (.d.ts) let TypeScript understand JavaScript libraries, package APIs, globals, and generated output; they are erased from runtime and must accurately match the shipped code.

Declaration forms and package delivery

A declaration can describe modules, functions, classes, interfaces, namespaces, and ambient globals. A package can publish declarations through types or typings metadata and conditional exports entries. TypeScript may resolve bundled declarations, a separate @types package, or inferred JavaScript depending on package metadata and compiler settings. Module format and declaration format matter: ESM and CommonJS consumers may need correctly corresponding declarations in dual packages.

declare describes a value that exists elsewhere; it does not create that value. A declaration mismatch can make invalid usage type-check or valid usage fail to type-check. any inside declarations erodes checking for all consumers. Declaration maps can link generated declarations back to source for editor navigation.

Authoring and validation

Prefer declarations generated from checked TypeScript source when possible. Handwritten declarations should mirror runtime exports exactly and avoid accidentally declaring globals. Validate from an external consumer fixture using the package's public entry points and supported module resolution modes. Test package tarballs, not only workspace source, because publishing may omit files or expose different paths.

Interview questions

  1. Do .d.ts files run? No; they supply static descriptions only.
  2. What does declare mean? Tell the checker a value exists; it does not implement or emit it.
  3. Why test declarations externally? Consumers resolve the packed package and public exports differently from repository source.
  4. What is a declaration mismatch? The type contract disagrees with runtime behavior, causing false safety or unusable APIs.
  5. Where do types belong in package exports? In metadata/conditional export mappings consistent with runtime entry points and module formats.

References