tsdown-migrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrating from tsup to tsdown

从tsup迁移至tsdown

Knowledge base for AI agents to migrate tsup projects to tsdown — the Rolldown-powered library bundler.

供AI Agent使用的知识库，用于将tsup项目迁移至tsdown——基于Rolldown的库打包工具。

When to Use

适用场景

Migrating a project from tsup to tsdown
Understanding differences between tsup and tsdown options
Reviewing or fixing post-migration configuration issues
Advising users on tsup→tsdown compatibility

将项目从tsup迁移至tsdown
了解tsup与tsdown的选项差异
排查或修复迁移后的配置问题
为用户提供tsup→tsdown兼容性建议

Migration Overview

迁移概述

Follow these steps to migrate a tsup project:

Rename config file:
```
tsup.config.*
```
→
```
tsdown.config.*
```
Update imports:
```
'tsup'
```
→
```
'tsdown'
```
Apply option mappings: Rename/transform options per tables below
Preserve tsup defaults: Explicitly set options that differ (format, clean, dts, target)
Update package.json: Dependencies, scripts, root config field
Remove unsupported options: Replace with alternatives where available
Test build: Run
```
tsdown
```
and verify output

按照以下步骤迁移tsup项目：

重命名配置文件：
```
tsup.config.*
```
→
```
tsdown.config.*
```
更新导入语句：
```
'tsup'
```
→
```
'tsdown'
```
应用选项映射：根据下方表格重命名/转换选项
保留tsup默认值：显式设置存在差异的选项（format、clean、dts、target）
更新package.json：依赖项、脚本、根配置字段
移除不支持的选项：如有可用方案则替换为替代选项
测试构建：运行
```
tsdown
```
并验证输出结果

Config File Migration

配置文件迁移

File Rename

文件重命名

tsup	tsdown
`tsup.config.ts`	`tsdown.config.ts`
`tsup.config.cts`	`tsdown.config.cts`
`tsup.config.mts`	`tsdown.config.mts`
`tsup.config.js`	`tsdown.config.js`
`tsup.config.cjs`	`tsdown.config.cjs`
`tsup.config.mjs`	`tsdown.config.mjs`
`tsup.config.json`	`tsdown.config.json`

tsup	tsdown
`tsup.config.ts`	`tsdown.config.ts`
`tsup.config.cts`	`tsdown.config.cts`
`tsup.config.mts`	`tsdown.config.mts`
`tsup.config.js`	`tsdown.config.js`
`tsup.config.cjs`	`tsdown.config.cjs`
`tsup.config.mjs`	`tsdown.config.mjs`
`tsup.config.json`	`tsdown.config.json`

Import and Identifier Changes

导入与标识符变更

// Before
import { defineConfig } from 'tsup'

// After
import { defineConfig } from 'tsdown'

Replace all identifiers:

tsup

→

tsdown

TSUP

→

TSDOWN

// 迁移前
import { defineConfig } from 'tsup'

// 迁移后
import { defineConfig } from 'tsdown'

替换所有标识符：

tsup

→

tsdown

，

TSUP

→

TSDOWN

。

Option Mappings

选项映射

Property Renames

属性重命名

tsup	tsdown	Notes
`cjsInterop`	`cjsDefault`	CJS default export handling
`esbuildPlugins`	`plugins`	Now uses Rolldown/Unplugin plugins

tsup	tsdown	说明
`cjsInterop`	`cjsDefault`	CJS默认导出处理
`esbuildPlugins`	`plugins`	现在使用Rolldown/Unplugin插件

Deprecated but Compatible

已弃用但仍兼容

These tsup options still work in tsdown for backward compatibility, but emit deprecation warnings and will be removed in a future version. Migrate them immediately.

tsup (deprecated)	tsdown (preferred)	Notes
`entryPoints`	`entry`	Also deprecated in tsup itself
`publicDir`	`copy`	Copy static files to output
`bundle: true`	(remove)	Bundle is default behavior
`bundle: false`	`unbundle: true`	Preserve file structure
`removeNodeProtocol: true`	`nodeProtocol: 'strip'`	Strip `node:` prefix
`injectStyle: true`	`css: { inject: true }`	CSS injection
`injectStyle: false`	(remove)	Default behavior
`external: [...]`	`deps: { neverBundle: [...] }`	Moved to deps namespace
`noExternal: [...]`	`deps: { alwaysBundle: [...] }`	Moved to deps namespace
`skipNodeModulesBundle`	`deps: { skipNodeModulesBundle: true }`	Moved to deps namespace

这些tsup选项在tsdown中仍可使用以实现向后兼容，但会输出弃用警告，且将在未来版本中移除。请立即迁移这些选项。

tsup（已弃用）	tsdown（推荐）	说明
`entryPoints`	`entry`	tsup自身也已弃用该选项
`publicDir`	`copy`	将静态文件复制到输出目录
`bundle: true`	(移除)	打包为默认行为
`bundle: false`	`unbundle: true`	保留文件结构
`removeNodeProtocol: true`	`nodeProtocol: 'strip'`	移除 `node:` 前缀
`injectStyle: true`	`css: { inject: true }`	CSS注入
`injectStyle: false`	(移除)	默认行为
`external: [...]`	`deps: { neverBundle: [...] }`	移至deps命名空间下
`noExternal: [...]`	`deps: { alwaysBundle: [...] }`	移至deps命名空间下
`skipNodeModulesBundle`	`deps: { skipNodeModulesBundle: true }`	移至deps命名空间下

Dependency Namespace Moves

依赖项命名空间迁移

Dependencies config moved under

deps

namespace. If both

external

and

noExternal

exist, merge into a single

deps

object:

// Before (tsup)
export default defineConfig({
  external: ['react'],
  noExternal: ['lodash-es'],
})

// After (tsdown)
export default defineConfig({
  deps: {
    neverBundle: ['react'],
    alwaysBundle: ['lodash-es'],
  },
})

tsdown also adds

deps.onlyBundle

(whitelist of allowed bundled packages) — no tsup equivalent.

依赖项配置已移至

deps

命名空间下。如果同时存在

external

和

noExternal

，请合并为单个

deps

对象：

// 迁移前（tsup）
export default defineConfig({
  external: ['react'],
  noExternal: ['lodash-es'],
})

// 迁移后（tsdown）
export default defineConfig({
  deps: {
    neverBundle: ['react'],
    alwaysBundle: ['lodash-es'],
  },
})

tsdown还新增了

deps.onlyBundle

（允许打包的包白名单）——tsup无对应功能。

Plugin Import Transforms

插件导入转换

// Before (tsup - esbuild plugins)
import plugin from 'unplugin-example/esbuild'

// After (tsdown - Rolldown plugins)
import plugin from 'unplugin-example/rolldown'

All

unplugin-*/esbuild

imports should change to

unplugin-*/rolldown

For complete before/after examples of every transformation, see guide-option-mappings.md.

// 迁移前（tsup - esbuild插件）
import plugin from 'unplugin-example/esbuild'

// 迁移后（tsdown - Rolldown插件）
import plugin from 'unplugin-example/rolldown'

所有

unplugin-*/esbuild

导入应改为

unplugin-*/rolldown

。

如需查看所有转换的完整前后示例，请参阅guide-option-mappings.md。

Default Value Differences

默认值差异

tsdown changes several defaults from tsup. When migrating, explicitly set these to preserve tsup behavior, then let the user decide which new defaults to adopt.

Option	tsup Default	tsdown Default	Migration Action
`format`	`'cjs'`	`'esm'`	Set `format: 'cjs'` to preserve
`clean`	`false`	`true`	Set `clean: false` to preserve
`dts`	`false`	Auto-enabled if `types` / `typings` in package.json	Set `dts: false` to preserve
`target`	(none)	Auto-reads from `engines.node` in package.json	Set `target: false` to preserve

After migration, suggest the user review these — tsdown's defaults are generally better:

ESM is the modern standard
Cleaning output prevents stale files
Auto DTS from package.json reduces config
Auto target from engines.node ensures consistency

tsdown修改了tsup的多个默认值。迁移时，请显式设置这些选项以保留tsup的行为，之后再由用户决定是否采用新默认值。

选项	tsup默认值	tsdown默认值	迁移操作
`format`	`'cjs'`	`'esm'`	设置 `format: 'cjs'` 以保留原行为
`clean`	`false`	`true`	设置 `clean: false` 以保留原行为
`dts`	`false`	若package.json中存在 `types` / `typings` 则自动启用	设置 `dts: false` 以保留原行为
`target`	(无)	从package.json的 `engines.node` 自动读取	设置 `target: false` 以保留原行为

迁移完成后，建议用户评估这些选项——tsdown的默认值通常更优：

ESM是现代标准
清理输出目录可避免残留文件
从package.json自动生成DTS可减少配置
从engines.node自动读取target可确保一致性

Unsupported Options

不支持的选项

These tsup options have no direct equivalent in tsdown. Remove them and inform the user.

tsup Option	Status	Alternative
`splitting`	Always enabled	Remove — code splitting cannot be disabled in tsdown
`metafile`	Not available	Suggest `devtools: true` for Vite DevTools bundle analysis
`swc`	Not supported	Remove — tsdown uses oxc for transformation (built-in)
`experimentalDts`	Not supported	Use the `dts` option instead
`legacyOutput`	Not supported	Remove — no alternative
`plugins` (tsup experimental)	Incompatible	Migrate to Rolldown plugins manually; tsup's plugin API differs from Rolldown's

这些tsup选项在tsdown中无直接等效功能。请移除它们并告知用户。

tsup选项	状态	替代方案
`splitting`	始终启用	移除——tsdown中无法禁用代码分割
`metafile`	暂不支持	建议使用 `devtools: true` 通过Vite DevTools分析打包内容
`swc`	不支持	移除——tsdown内置使用oxc进行代码转换
`experimentalDts`	不支持	使用 `dts` 选项替代
`legacyOutput`	不支持	移除——无替代方案
`plugins` （tsup实验性）	不兼容	手动迁移至Rolldown插件；tsup的插件API与Rolldown不同

Package.json Migration

package.json迁移

Scripts

脚本

Replace

tsup

and

tsup-node

with

tsdown

in all script commands:

json

// Before
{
  "scripts": {
    "build": "tsup src/index.ts",
    "dev": "tsup --watch"
  }
}

// After
{
  "scripts": {
    "build": "tsdown src/index.ts",
    "dev": "tsdown --watch"
  }
}

在所有脚本命令中将

tsup

和

tsup-node

替换为

tsdown

：

json

// 迁移前
{
  "scripts": {
    "build": "tsup src/index.ts",
    "dev": "tsup --watch"
  }
}

// 迁移后
{
  "scripts": {
    "build": "tsdown src/index.ts",
    "dev": "tsdown --watch"
  }
}

Dependencies

依赖项

Location	Action
`dependencies.tsup`	Rename to `dependencies.tsdown`
`devDependencies.tsup`	Rename to `devDependencies.tsdown`
`optionalDependencies.tsup`	Rename to `optionalDependencies.tsdown`
`peerDependencies.tsup`	Rename to `peerDependencies.tsdown`
`peerDependenciesMeta.tsup`	Rename to `peerDependenciesMeta.tsdown`

位置	操作
`dependencies.tsup`	重命名为 `dependencies.tsdown`
`devDependencies.tsup`	重命名为 `devDependencies.tsdown`
`optionalDependencies.tsup`	重命名为 `optionalDependencies.tsdown`
`peerDependencies.tsup`	重命名为 `peerDependencies.tsdown`
`peerDependenciesMeta.tsup`	重命名为 `peerDependenciesMeta.tsdown`

Root Config Field

根配置字段

If package.json has a root-level

tsup

field (inline config), rename to

tsdown

json

// Before
{ "tsup": { "entry": ["src/index.ts"] } }

// After
{ "tsdown": { "entry": ["src/index.ts"] } }

For detailed package.json examples, see guide-package-json.md.

如果package.json中存在根级别的

tsup

字段（内联配置），请重命名为

tsdown

：

json

// 迁移前
{ "tsup": { "entry": ["src/index.ts"] } }

// 迁移后
{ "tsdown": { "entry": ["src/index.ts"] } }

如需查看详细的package.json示例，请参阅guide-package-json.md。

New tsdown Features

tsdown新增功能

After migration, suggest these tsdown-exclusive features to the user:

Feature	Config	Description
Node protocol	`nodeProtocol: true \| 'strip'`	Add or strip `node:` prefix on built-in imports
Workspace	`workspace: 'packages/*'`	Build multiple packages in a monorepo
Package exports	`exports: true`	Auto-generate `exports` field in package.json
Package validation	`publint: true` , `attw: true`	Lint package and check type correctness
Executable	`exe: true`	Bundle as Node.js standalone executable (SEA)
DevTools	`devtools: true`	Vite DevTools integration for bundle analysis
Hooks	`hooks: { 'build:done': ... }`	Lifecycle hooks: `build:prepare` , `build:before` , `build:done`
CSS modules	`css: { modules: { ... } }`	Scoped class names for `.module.css` files
Glob import	`globImport: true`	Support `import.meta.glob` (Vite-style)

For detailed comparisons, see guide-differences-detailed.md.

迁移完成后，可为用户推荐以下tsdown专属功能：

功能	配置	说明
Node协议	`nodeProtocol: true \| 'strip'`	为内置导入添加或移除 `node:` 前缀
工作区	`workspace: 'packages/*'`	在单体仓库中构建多个包
包导出	`exports: true`	自动在package.json中生成 `exports` 字段
包验证	`publint: true` , `attw: true`	检查包的规范与类型正确性
可执行文件	`exe: true`	打包为Node.js独立可执行文件（SEA）
开发工具	`devtools: true`	集成Vite DevTools用于打包分析
钩子	`hooks: { 'build:done': ... }`	生命周期钩子： `build:prepare` 、 `build:before` 、 `build:done`
CSS模块	`css: { modules: { ... } }`	为 `.module.css` 文件生成作用域类名
Glob导入	`globImport: true`	支持 `import.meta.glob` （Vite风格）

如需详细对比，请参阅guide-differences-detailed.md。

References

参考资料

Topic	Description	Reference
Option Mappings	Complete before/after for every option transform	guide-option-mappings
Detailed Differences	Architecture, features, compatibility comparison	guide-differences-detailed
Package.json	Dependency, script, and config field migration	guide-package-json

主题	说明	参考链接
选项映射	所有选项转换的完整前后示例	guide-option-mappings
详细差异	架构、功能、兼容性对比	guide-differences-detailed
package.json迁移	依赖项、脚本与配置字段迁移	guide-package-json

Migration Checklist

迁移检查清单

Use this checklist when performing a migration:

- [ ] Rename tsup.config.* → tsdown.config.*
- [ ] Update import from 'tsup' to 'tsdown'
- [ ] Replace tsup/TSUP identifiers with tsdown/TSDOWN
- [ ] Apply property renames (cjsInterop→cjsDefault, esbuildPlugins→plugins)
- [ ] Migrate deprecated options (publicDir→copy, bundle→unbundle, removeNodeProtocol→nodeProtocol, injectStyle→css.inject)
- [ ] Move external/noExternal/skipNodeModulesBundle into deps namespace
- [ ] Update unplugin imports from /esbuild to /rolldown
- [ ] Set explicit defaults to preserve tsup behavior (format, clean, dts, target)
- [ ] Remove unsupported options (splitting, metafile, swc, etc.)
- [ ] Update package.json scripts (tsup→tsdown)
- [ ] Update package.json dependencies
- [ ] Rename root-level tsup config field if present
- [ ] Run tsdown and verify build output
- [ ] Suggest new tsdown features to the user

执行迁移时可使用以下检查清单：

- [ ] 将tsup.config.*重命名为tsdown.config.*
- [ ] 将导入语句从'tsup'更新为'tsdown'
- [ ] 将tsup/TSUP标识符替换为tsdown/TSDOWN
- [ ] 应用属性重命名（cjsInterop→cjsDefault、esbuildPlugins→plugins）
- [ ] 迁移已弃用选项（publicDir→copy、bundle→unbundle、removeNodeProtocol→nodeProtocol、injectStyle→css.inject）
- [ ] 将external/noExternal/skipNodeModulesBundle移至deps命名空间下
- [ ] 将unplugin导入从/esbuild改为/rolldown
- [ ] 显式设置默认值以保留tsup行为（format、clean、dts、target）
- [ ] 移除不支持的选项（splitting、metafile、swc等）
- [ ] 更新package.json中的脚本（tsup→tsdown）
- [ ] 更新package.json中的依赖项
- [ ] 如有根级tsup配置字段则重命名
- [ ] 运行tsdown并验证构建输出
- [ ] 为用户推荐tsdown新增功能