.d.ts-файлы: ambient-объявления, аугментация и публичная поверхность типов

declare: формы без реализаций

.d.ts-файл содержит только информацию о типах — исполняемый код запрещён, поэтому всё declare-ится. Так описывают значение, которое существует в рантайме, но которое TypeScript не видит (глобал из тега script, нетипизированный npm-пакет):

// globals.d.ts — ambient-объявления (нет import/export = это СКРИПТ, глобальная область)
declare const __APP_VERSION__: string;     // внедряется бандлером во время сборки
declare function gtag(...args: unknown[]): void;

interface Window {                          // сливается со встроенным Window
  dataLayer: unknown[];
}

Файл без import/export верхнего уровня — это скрипт: его объявления глобальны. Файл с любым import/export верхнего уровня — это модуль: его объявления локальны, если не обёрнуты в declare global. Это различие module-vs-script — корень большинства провалов аугментации.

Ambient-модули: типизация нетипизированной зависимости

Когда ты import-ируешь JS-пакет без типов и без @types/..., TypeScript даёт ошибку TS7016. declare module "name" изобретает ambient-объявление модуля, чтобы закрыть пробел:

// 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;
}

Wildcard-форма типизирует целые классы импортов — например, импорты ассетов под бандлером:

declare module "*.svg" {
  const url: string;     // загрузчик Vite/webpack превращает файл в строку-URL
  export default url;
}

Module-аугментация: расширение чужих типов

Чтобы добавить к типу, который экспортирует другой модуль, переоткрой этот модуль через declare module изнутри своего модуля (файл должен иметь собственный import/export):

// augment.ts — есть импорты, значит это МОДУЛЬ
import "express"; // гарантируем загрузку целевого модуля
declare module "express-serve-static-core" {
  interface Request { user?: { id: string; roles: string[] } } // сливается с Request из Express
}
export {}; // для надёжности: гарантирует контекст модуля

Для глобальных типов (Window, Array, globalThis) аугментацию надо обернуть в declare global — и охватывающий файл всё равно должен быть модулем:

// env.d.ts
export {}; // делает файл модулем, чтобы `declare global` был здесь легален
declare global {
  interface Window { __APP_VERSION__: string }
  namespace NodeJS { interface ProcessEnv { DATABASE_URL: string } }
}

Emit и поставка типов

Когда публикуешь библиотеку, поставляемые .d.ts-файлы и есть твой API-контракт для редактора и проверщика типов каждого потребителя. Сделай emit неверно — и потребители увидят ошибки TS4023 или сломанный «go to definition», даже если рантайм работает нормально.

declaration: true заставляет tsc генерировать .d.ts рядом с каждым .js. declarationMap: true генерирует .d.ts.map, чтобы «go to definition» у потребителя прыгал в твой настоящий исходник, а не в сгенерированный .d.ts. В package.json ты указываешь потребителям на них через types (или условие types в exports):

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

typeRoots/types (опции компилятора, отличные от поля в package.json) управляют тем, какие @types-пакеты включаются: types: [] отключает авто-включение каждого @types/* из node_modules — частый фикс для «глобал из какого-то транзитивного @types загрязнил мой проект».

export type vs export

В .d.ts, который ты пишешь руками, предпочитай export type { Foo } для type-only экспортов, чтобы потребители (и однофайловые транспиляторы) знали, что он не несёт runtime-значения. Обычный export { Foo }, где Foo — тип, работает для потребителей типов, но неоднозначен для инструментов, стирающих типы пофайлово.