Как это работает

На этой странице кратко описано, что tsdown делает из коробки и какие опции меняют это поведение. Подробности по каждой теме см. в соответствующих разделах по ссылкам.

Умные значения по умолчанию

tsdown анализирует package.json и tsconfig.json и подбирает разумные значения. Вот что происходит автоматически:

Когда tsdown обнаруживает...	Он...
dependencies / peerDependencies в package.json	Выносит их наружу (не включает в бандл)
Импорт из devDependency в коде	Включает пакет в выходной бандл
Поле types или typings в package.json	Включает генерацию .d.ts
isolatedDeclarations в tsconfig.json	Использует быстрый путь oxc-transform для dts
engines.node в package.json	Определяет целевое окружение (target) по нему
type: "module" в package.json	Использует расширение .js для ESM (вместо .mjs)
entry не задан, но есть src/index.ts	Берёт его как точку входа по умолчанию
platform: "node" (по умолчанию)	Включает fixedExtension (.mjs/.cjs)
Сборка в двух форматах с exports: true	Заполняет поля main/module в package.json
Изменения конфига в режиме наблюдения	Перезапускает сборку

Ниже каждая область описана подробнее.

Зависимости

При публикации библиотеки у пользователей устанавливаются её dependencies и peerDependencies. Нет смысла включать их в бандл — в рантайме они уже будут доступны.

Поведение по умолчанию:

• dependencies и peerDependencies выносятся наружу — в выводе остаются import / require, пакеты в бандл не попадают.
• devDependencies попадают в бандл, если импортированы. У пользователей они не ставятся, поэтому код из dev-зависимости автоматически встраивается в вывод.
• Фантомные зависимости (есть в node_modules, но не указаны в package.json) обрабатываются как devDependencies — в бандл только если используются.

Основные опции:

Опция	Назначение
deps.onlyAllowBundle	Список зависимостей, которые разрешено включать в бандл. Любая другая зависимость в бандле приведёт к ошибке. Помогает отловить случайное встраивание в больших проектах.
deps.neverBundle	Дополнительные пакеты, которые всегда выносить наружу (никогда не бандлить).
deps.alwaysBundle	Принудительно включать указанные пакеты в бандл, даже если они в dependencies.
deps.skipNodeModulesBundle	Не разрешать и не бандлить ничего из node_modules.

Подробнее: Зависимости.

Формат вывода

По умолчанию tsdown выдаёт ESM. Можно собрать несколько форматов за один запуск и задать свои опции для каждого формата.

Основные опции:

Опция	Назначение
format	Значения: esm, cjs, iife, umd. Несколько форматов: format: ['esm', 'cjs'].
shims	Подставлять прослойки совместимости (например, __dirname для ESM, import.meta для CJS).

Подробнее: Формат вывода.

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

tsdown генерирует .d.ts, чтобы у пользователей библиотеки была полная поддержка TypeScript.

Поведение по умолчанию:

• Если в package.json есть поле types или typings, генерация dts включается сама.
• При включённом isolatedDeclarations в tsconfig.json tsdown использует быстрый путь oxc-transform. Иначе — компилятор TypeScript.

Основные опции:

Опция	Назначение
dts	Включить/выключить dts или передать объект с настройками (resolver, sourcemap и др.).

Подробнее: Файлы деклараций.

Экспорты пакета

Поле exports в package.json указывает, как разрешать точки входа вашего пакета — для пользователей и бандлеров.

Поведение по умолчанию:

• Автогенерация exports выключена. Поле exports вы заполняете сами.

При exports: true:

• tsdown анализирует точки входа и выходные файлы и сам заполняет в package.json поля exports, main, module и types.
• Для сборки в двух форматах (ESM + CJS) создаются условные экспорты с условиями import и require.

Основные опции:

Опция	Назначение
exports	true — включить автогенерацию; объект — тонкая настройка.
exports.all	Экспортировать все выходные файлы, не только точки входа.
exports.devExports	В разработке указывать экспорты на исходники для лучшей поддержки в редакторе.
exports.customExports	Функция для изменения или дополнения сгенерированных экспортов.

Подробнее: Экспорты пакета.

Валидация пакета

tsdown интегрирован с publint и attw, чтобы находить ошибки перед публикацией в npm.

Поведение по умолчанию:

• Оба инструмента выключены по умолчанию и являются опциональными зависимостями.

Что проверяют:

• publint проверяет конфигурацию package.json: что exports, main, module и types указывают на существующие файлы, форматы модулей корректны, типичные ошибки подсвечиваются.
• attw (Are the types wrong?) проверяет, что TypeScript-декларации корректно разрешаются при разных стратегиях (node10, node16, bundler), в том числе находит неверные ESM/CJS декларации.

Основные опции:

Опция	Назначение
publint	Включить: true или 'ci-only'.
attw	Включить: true или объект с profile, level, ignoreRules.

Подробнее: Валидация пакета.

Остальные значения по умолчанию

Ещё несколько вещей, которые tsdown настраивает сам:

• Директория вывода — по умолчанию dist/. Перед каждой сборкой она очищается. Чтобы не очищать, используйте --no-clean. См. Очистка.
• Tree-shaking — включён по умолчанию, мёртвый код удаляется из вывода. См. Tree-shaking.
• Платформа — по умолчанию node. См. Платформа.
• Целевое окружение — берётся из поля engines в package.json или по умолчанию соответствует последней стабильной версии Node.js. См. Целевое окружение (target).