Настройка tsconfig.json и файлы объявлений

Когда tsc компилирует проект, он не просто стирает аннотации типов и оставляет чистый JavaScript. В зависимости от настроек в tsconfig.json, компилятор может параллельно создавать ещё три вида файлов: файлы объявлений, карты объявлений и карты исходников. Каждый из них решает свою задачу и адресован разным потребителям — либо другим разработчикам, либо инструментам отладки.

Разница станет понятнее, если представить, что итоговый JavaScript уходит в браузер или на сервер, а вот файлы объявлений остаются рядом с исходным кодом как «инструкция» для TypeScript-компилятора, который позже будет использовать вашу библиотеку.

Файлы объявлений .d.ts

Файл объявления, или declaration file, содержит только сигнатуры типов — без реализации функций и без логики. Это как бы «скелет» модуля: какие функции экспортируются, какие у них параметры и что они возвращают.

// math.ts
export function sum(a: number, b: number): number {
  return a + b;
}

После компиляции с включённой опцией declaration рядом с math.js появится файл math.d.ts:

export declare function sum(a: number, b: number): number;

Такие файлы нужны, если вы публикуете библиотеку. Пользователь вашего пакета получает обычный JavaScript, а IDE — файл .d.ts, благодаря которому автодополнение и проверка типов продолжают работать, даже если сама библиотека написана на чистом JavaScript.

Карты объявлений .d.ts.map

Declaration map — это карта соответствия между файлом объявления и оригинальным .ts-файлом. Без неё редактор кода при переходе «к определению» (go to definition) приводит вас в сгенерированный .d.ts-файл, где нет реализации — только типы. С включённой картой редактор способен перейти сразу в исходный .ts-файл, туда, где функция действительно написана.

Source map .js.map

Source map связывает скомпилированный .js-файл с исходным .ts. Она нужна не для типов, а для отладки в браузере или Node.js: когда в консоли возникает ошибка или вы ставите точку останова, среда показывает строку в оригинальном TypeScript-файле, а не в сгенерированном JavaScript, который реальный человек обычно не читает.

Все три типа файлов управляются флагами компилятора в секции compilerOptions:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true
  }
}

Коротко о смысле каждого флага:

Обратите внимание: declarationMap без declaration не сработает — карта объявлений существует только вместе с самим файлом объявления, компилятор выдаст ошибку, если включить только её.

Допустим, есть небольшой проект с такой структурой:

src/
  index.ts
tsconfig.json

После запуска tsc с конфигом из примера выше в папке dist появятся сразу четыре файла:

1. index.js — рабочий JavaScript-код
2. index.d.ts — файл объявления с типами
3. index.d.ts.map — карта для перехода из .d.ts в исходник
4. index.js.map — карта для отладки JavaScript

Если открыть index.d.ts.map или index.js.map в текстовом редакторе, внутри будет не читаемый человеком код, а сжатый JSON с координатами строк и колонок — эти файлы предназначены для инструментов, а не для чтения глазами.

Если вы пишете обычное приложение — сайт, серверный сервис, скрипт — которое не превращается в переиспользуемый пакет для других разработчиков, генерировать .d.ts обычно незачем. Типы нужны только во время разработки и проверки, а до конечного пользователя приложения долетает лишь JavaScript. В таких проектах declaration и declarationMap оставляют выключенными, а вот sourceMap часто включают — он полезен всегда, когда планируется отлаживать код в браузере или через Node.js инспектор.

tsconfig.json определяет не только то, как TypeScript превращается в JavaScript, но и какие вспомогательные файлы появляются рядом с результатом компиляции.

Файлы объявлений .d.ts нужны, чтобы делиться типами вместе с библиотекой, карты объявлений .d.ts.map возвращают редактору способность прыгать сразу в исходный код, а source map .js.map делает отладку скомпилированного JavaScript комфортной. Понимание того, когда включать каждый из этих флагов, помогает не захламлять проект лишними файлами и одновременно не терять удобство разработки там, где оно действительно нужно.

В следующем уроке мы вернёмся к синтаксису самого TypeScript — разберём интерфейсы, их расширение и композицию для описания сложных объектов.