Миграция с tsup

tsup - это мощный и широко используемый бандлер, который во многом похож на tsdown. В то время как tsup построен на базе esbuild, tsdown использует возможности Rolldown, обеспечивая более быструю и мощную сборку.

Руководство по миграции

Если вы сейчас используете tsup и хотите перейти на tsdown, процесс миграции очень прост благодаря специальной команде migrate:

npx tsdown-migrate

Для монорепозиториев можно указывать директории с помощью glob‑шаблонов:

npx tsdown-migrate packages/*

Или перечислить несколько директорий явно:

npx tsdown-migrate packages/foo packages/bar

WARNING

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

TIP

После миграции инструмент автоматически установит все зависимости. Команду нужно запускать из корневой директории вашего проекта.

Параметры миграции

Команда migrate поддерживает следующие параметры для настройки процесса миграции:

• [...dirs]: Указывает, какие директории нужно мигрировать. Поддерживает glob‑шаблоны (например, packages/*). Если параметр не задан, по умолчанию используется текущая директория.
• --dry-run (или -d): Выполняет пробный запуск миграции без внесения изменений.

С помощью этих опций вы легко сможете адаптировать процесс миграции под нужды вашего проекта.

Отличия от tsup

Хотя tsdown стремится быть максимально совместимым с tsup, есть некоторые различия, о которых стоит знать:

Значения по умолчанию

Опция	tsup	tsdown
format	'cjs'	'esm'
clean	false	true (очищает outDir перед каждой сборкой)
dts	false	Включается автоматически, если в package.json есть поле types или typings
target	(нет)	Определяется автоматически по engines.node в package.json

Переименованные опции

Некоторые опции были переименованы для большей ясности:

tsup	tsdown	Примечание
cjsInterop	cjsDefault	Обработка default-экспорта для CJS
esbuildPlugins	plugins	Используются плагины Rolldown и unplugin

Устаревшие, но совместимые опции

Следующие опции из tsup пока работают в tsdown ради обратной совместимости, но уже помечены как устаревшие и будут удалены в будущих версиях. Рекомендуем как можно скорее перейти на предпочтительные альтернативы.

tsup (устарело)	tsdown (предпочтительно)	Примечание
entryPoints	entry	Также устарело в самом tsup
publicDir	copy	Копирование статических файлов в вывод
bundle: false	unbundle: true	Инверсия в положительную форму
removeNodeProtocol: true	nodeProtocol: 'strip'	Более гибкое поведение с несколькими режимами
injectStyle: true	css: { inject: true }	Перенесено в пространство опций CSS
external: [...]	deps: { neverBundle: [...] }	Перенесено в пространство опций deps
noExternal: [...]	deps: { alwaysBundle: [...] }	Перенесено в пространство опций deps
skipNodeModulesBundle	deps: { skipNodeModulesBundle: true }	Перенесено в пространство опций deps

Также в tsdown есть опция deps.onlyBundle для списка разрешённых пакетов, которые можно включать в бандл.

Система плагинов

tsdown использует плагины Rolldown вместо плагинов esbuild. Если вы используете плагины unplugin, обновите путь импорта:

// Было (tsup)
import plugin from 'unplugin-example/esbuild'
// Стало (tsdown)
import plugin from 'unplugin-example/rolldown'

Неподдерживаемые опции

Следующие опции tsup недоступны в tsdown:

Опция	Статус	Альтернатива
splitting: false	Всегда включено	Code splitting нельзя отключить
metafile	Недоступно	Используйте devtools: true для анализа бандла через Vite DevTools
swc	Не поддерживается	tsdown использует oxc для преобразования (встроено)
experimentalDts	Заменено	Используйте опцию dts
legacyOutput	Не поддерживается	Альтернативы нет
plugins (экспериментально в tsup)	Несовместимо	Перейдите на плагины Rolldown

Если вам не хватает какой-либо опции, создайте issue и опишите, в каком случае она вам нужна.

Новые возможности в tsdown

tsdown предоставляет множество возможностей, которых нет в tsup:

• nodeProtocol: Управление обработкой импортов встроенных модулей Node.js:
  • true: Добавляет префикс node: к встроенным модулям (например, fs → node:fs)
  • 'strip': Удаляет префикс node: из импортов (например, node:fs → fs)
  • false: Оставляет импорты без изменений (по умолчанию)
• workspace: Сборка нескольких пакетов в монорепозитории через workspace: 'packages/*'
• exports: Автогенерация поля exports в package.json через exports: true
• publint / attw: Проверка пакета на типичные проблемы и корректность типов
• exe: Сборка в автономный исполняемый файл Node.js (SEA) через exe: true
• devtools: Интеграция с Vite DevTools для анализа бандла через devtools: true
• hooks: Хуки жизненного цикла (build:prepare, build:before, build:done) для добавления собственной логики в процесс сборки
• css: Полный CSS-конвейер с препроцессорами, Lightning CSS, PostCSS, CSS modules и code splitting
• globImport: Поддержка import.meta.glob (glob-импорты в стиле Vite)

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

TIP

Для миграции с пошаговыми подсказками доступен AI skill: npx skills add rolldown/tsdown --skill tsdown-migrate

Благодарности

tsdown не был бы возможен без вдохновения и вклада open-source сообщества. Мы выражаем искреннюю благодарность следующим проектам и людям:

• tsup: tsdown во многом вдохновлён tsup и даже использует части его кода. Простота и эффективность tsup были ориентиром при разработке tsdown.
• @egoist: Автор tsup, чья работа существенно повлияла на экосистему инструментов для JavaScript и TypeScript. Спасибо за вашу преданность делу и вклад в сообщество.