Файлы деклараций (dts)

Файлы деклараций (.d.ts) являются неотъемлемой частью TypeScript-библиотек, предоставляя определения типов, которые позволяют потребителям вашей библиотеки пользоваться проверкой типов в TypeScript и подсказками IntelliSense.

tsdown упрощает генерацию и упаковку файлов деклараций, делая работу с вашей библиотекой более комфортной.

NOTE

Установите typescript в ваш проект, чтобы генерация файлов деклараций работала правильно.

Как работает dts в tsdown

Для генерации и упаковки файлов деклараций .d.ts в tsdown используется встроенный плагин rolldown-plugin-dts. Этот плагин специально разработан для эффективной работы с файлами деклараций и полностью интегрирован в tsdown.

Если вы столкнетесь с какими-либо проблемами, связанными с генерацией .d.ts, пожалуйста, сообщайте о них напрямую в репозиторий rolldown-plugin-dts.

Включение генерации dts

Если в вашем package.json есть поле types или typings, генерация файлов деклараций будет включена по умолчанию в tsdown.

Вы также можете явно включить генерацию .d.ts файлов с помощью опции --dts в CLI или установив dts: true в файле конфигурации.

CLI

tsdown --dts

Конфигурационный файл

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  dts: true,
})

Карта деклараций (Declaration Map)

Карты деклараций позволяют сопоставлять файлы .d.ts с их исходными .ts файлами, что особенно полезно в монорепозиториях для улучшенной навигации и отладки. Подробнее читайте в документации TypeScript.

Включить карты деклараций можно одним из следующих способов (нет необходимости указывать оба):

Включение в tsconfig.json

Включите опцию declarationMap в разделе compilerOptions:

tsconfig.json

{
  "compilerOptions": {
    "declarationMap": true
  }
}

Включение в конфиге tsdown

Установите опцию dts.sourcemap в значение true в вашем конфиге tsdown:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  dts: {
    sourcemap: true,
  },
})

Особенности производительности

Производительность генерации файлов .d.ts зависит от конфигурации вашего tsconfig.json:

При включённом isolatedDeclarations

При включённой опции isolatedDeclarations в tsconfig.json для генерации .d.ts используется oxc-transform — это обеспечивает максимальную скорость и настоятельно рекомендуется для повышения производительности.

tsconfig.json

{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}

Без isolatedDeclarations

Если isolatedDeclarations не включён, tsdown будет использовать компилятор TypeScript для генерации файлов .d.ts. Хотя этот подход надёжен, он относительно медленнее по сравнению с oxc-transform.

TIP

Если для вашего рабочего процесса важна скорость, рассмотрите возможность включения isolatedDeclarations в tsconfig.json.

Сборка dts

• Для ESM вывода: Файлы .js и .d.ts генерируются в одном процессе сборки. Если вы столкнётесь с проблемами совместимости, пожалуйста, сообщите о них.
• Для CJS вывода: Используется отдельный процесс сборки исключительно для генерации .d.ts, чтобы обеспечить совместимость.

Расширенные параметры

rolldown-plugin-dts предоставляет несколько расширенных опций для настройки генерации .d.ts. Для подробного объяснения этих опций обратитесь к документации плагина.