Часто задаваемые вопросы

Почему tsdown не поддерживает режим заглушек (stub-mode)

tsdown не поддерживает режим заглушек из-за ряда ограничений и особенностей архитектуры:

• Режим заглушек требует ручного вмешательства. При каждом изменении именованных экспортов необходимо заново запускать команду создания заглушек, чтобы обновить их. Это нарушает рабочий процесс разработчика и может привести к несоответствиям в коде.
• Режим заглушек несовместим с плагинами. В этом режиме невозможно использовать плагины, а они часто необходимы для сложных сценариев и пользовательской логики сборки.

Рекомендуемые альтернативы

Вместо режима заглушек рекомендуется использовать более надежные и гибкие подходы:

1. Режим наблюдения (Watch Mode): Самое простое решение — запускать tsdown в режиме наблюдения. В этом случае сборка автоматически обновляется при изменениях в коде, хотя процесс должен постоянно работать в фоновом режиме.

2. Использование exports.devExports для разделения Dev/Prod-сред: Для более продвинутой и устойчивой настройки можно использовать опцию exports.devExports чтобы указать разные пути экспорта для разработки и продакшена. Это позволяет в процессе разработки ссылаться на исходные файлы, а при сборке — на готовые.

   • Если вы используете плагины: Рассмотрите вариант запуска кода через vite-node, который поддерживает плагины.
   • Если вы не используете плагины: Можно воспользоваться легковесными раннерами для TypeScript, такими как tsx, jiti, или unrun.
   • Если вы не используете плагины и ваш код совместим со встроенной поддержкой TypeScript в Node.js: Начиная с Node.js версии 22.18.0 и выше, TypeScript-файлы можно запускать напрямую без дополнительных инструментов.

Эти альтернативы обеспечивают более плавный и стабильный процесс разработки по сравнению с режимом заглушек, особенно по мере роста проекта или при необходимости поддержки плагинов. Более подробное объяснение этого решения доступно в этом комментарии на GitHub.

Чем tsdown отличается от tsup?

tsdown можно считать преемником tsup по духу: вместо esbuild используется Rolldown. Основные отличия:

• Быстрее сборка: Rolldown даёт заметный выигрыш по скорости, особенно на крупных проектах.
• Богаче экосистема плагинов: поддерживаются плагины Rolldown, Rollup и unplugin.
• Больше возможностей из коробки: CSS, упаковка в исполняемый файл, режим workspace и проверка пакета (publint / attw).

Подробное сравнение и шаги миграции — в разделе Миграция с tsup.

Можно ли использовать tsdown в монорепозитории?

Да. В tsdown есть встроенная поддержка workspace. Включите режим workspace флагом --workspace (или -W): будут автоматически найдены пакеты монорепозитория. Конкретные пакеты можно отобрать через --filter (или -F):

tsdown -W -F my-package

Конфигурация из корня репозитория автоматически наследуется пакетами workspace.

Почему в бандл попадают зависимости?

По умолчанию пакеты из dependencies и peerDependencies в package.json не включаются в бандл. В вывод сборки обычно попадает то, что вы действительно импортируете из devDependencies или из node_modules без записи в package.json («фантомные» зависимости). Чтобы зависимости из node_modules не попадали в бандл, укажите в поле deps:

export default defineConfig({
  deps: {
    skipNodeModulesBundle: true,
  },
})

Другие варианты настройки — в разделе Зависимости.

Как генерировать файлы объявлений типов (dts)?

Включите опцию dts:

export default defineConfig({
  dts: true,
})

tsdown сам включает генерацию dts, если в package.json есть поля types или typings, либо если в exports указаны условия для типов. Дополнительные настройки — в разделе Файлы деклараций.