name: tsdown description: 使用Rolldown提供极速支持的TypeScript和JavaScript库打包工具。适用于构建库、生成类型声明、打包多种格式或从tsup迁移。

tsdown - 优雅的库打包器

基于Rolldown和Oxc的极速TypeScript/JavaScript库打包器。

使用场景

为npm构建TypeScript/JavaScript库
生成TypeScript声明文件 (.d.ts)
打包多种格式 (ESM, CJS, IIFE, UMD)
通过摇树优化和压缩优化包体积
以最小改动从tsup迁移
构建React、Vue、Solid或Svelte组件库

快速开始

# 安装
pnpm add -D tsdown

# 基本用法
npx tsdown

# 使用配置文件
npx tsdown --config tsdown.config.ts

# 监听模式
npx tsdown --watch

# 从tsup迁移
npx tsdown-migrate

基本配置

import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['./src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
})

核心参考

主题	描述	参考文档
快速开始	安装、首次打包、CLI基础	guide-getting-started
配置文件	配置文件格式、多配置、工作区	option-config-file
CLI参考	所有CLI命令和选项	reference-cli
从tsup迁移	迁移指南和兼容性说明	guide-migrate-from-tsup
插件	Rolldown、Rollup、Unplugin支持	advanced-plugins
钩子	用于自定义逻辑的生命周期钩子	advanced-hooks
编程式API	从Node.js脚本构建	advanced-programmatic
Rolldown选项	直接传递选项给Rolldown	advanced-rolldown-options
CI环境	CI检测、`'ci-only'` / `'local-only'` 值	advanced-ci

构建选项

选项	用法	参考文档
入口点	`entry: ['src/.ts', '!/.test.ts']`	option-entry
输出格式	`format: ['esm', 'cjs', 'iife', 'umd']`	option-output-format
输出目录	`outDir: 'dist'`, `outExtensions`	option-output-directory
类型声明	`dts: true`, `dts: { sourcemap, compilerOptions, vue }`	option-dts
目标环境	`target: 'es2020'`, `target: 'esnext'`	option-target
平台	`platform: 'node'`, `platform: 'browser'`	option-platform
摇树优化	`treeshake: true`, 自定义选项	option-tree-shaking
压缩	`minify: true`, `minify: 'dce-only'`	option-minification
源码映射	`sourcemap: true`, `'inline'`, `'hidden'`	option-sourcemap
监听模式	`watch: true`, 监听选项	option-watch-mode
清理	`clean: true`, 清理模式	option-cleaning
日志级别	`logLevel: 'silent'`, `failOnWarn: 'ci-only'`	option-log-level

依赖处理

功能	用法	参考文档
外部依赖	`external: ['react', /^@myorg\//]`	option-dependencies
内联依赖	`noExternal: ['dep-to-bundle']`	option-dependencies
自动外部化	自动外部化peer依赖/依赖	option-dependencies

输出增强

功能	用法	参考文档
垫片	`shims: true` - 添加ESM/CJS兼容性	option-shims
CJS默认导出	`cjsDefault: true` (默认) / `false`	option-cjs-default
包导出	`exports: true` - 自动生成exports字段	option-package-exports
CSS处理	[实验性] 仍在开发中	option-css
非打包模式	`unbundle: true` - 保留目录结构	option-unbundle
包验证	`publint: true`, `attw: true` - 验证包	option-lint

框架与运行时支持

框架	指南	参考文档
React	JSX转换、快速刷新	recipe-react
Vue	SFC支持、JSX	recipe-vue
WASM	通过 `rolldown-plugin-wasm` 支持WebAssembly模块	recipe-wasm

常用模式

基础库打包

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
})

多入口点

export default defineConfig({
  entry: {
    index: 'src/index.ts',
    utils: 'src/utils.ts',
    cli: 'src/cli.ts',
  },
  format: ['esm', 'cjs'],
  dts: true,
})

浏览器库 (IIFE/UMD)

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['iife'],
  globalName: 'MyLib',
  platform: 'browser',
  minify: true,
})

React组件库

export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  dts: true,
  external: ['react', 'react-dom'],
  plugins: [
    // React快速刷新支持
  ],
})

保留目录结构

export default defineConfig({
  entry: ['src/**/*.ts', '!**/*.test.ts'],
  unbundle: true, // 保留文件结构
  format: ['esm'],
  dts: true,
})

CI感知配置

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  failOnWarn: 'ci-only',
  publint: 'ci-only',
  attw: 'ci-only',
})

WASM支持

import { wasm } from 'rolldown-plugin-wasm'
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [wasm()],
})

高级钩子使用

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  hooks: {
    'build:before': async (context) => {
      console.log('构建中...')
    },
    'build:done': async (context) => {
      console.log('构建完成!')
    },
  },
})

配置特性

多配置

导出数组以支持多个构建配置：

export default defineConfig([
  {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    dts: true,
  },
  {
    entry: ['src/cli.ts'],
    format: ['esm'],
    platform: 'node',
  },
])

条件配置

使用函数实现动态配置：

export default defineConfig((options) => {
  const isDev = options.watch
  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
  }
})

工作区/单体仓库

使用通配符模式构建多个包：

export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
})

CLI快速参考

# 基础命令
tsdown                          # 构建一次
tsdown --watch                  # 监听模式
tsdown --config custom.ts       # 自定义配置
npx tsdown-migrate              # 从tsup迁移

# 输出选项
tsdown --format esm,cjs        # 多种格式
tsdown --outDir lib            # 自定义输出目录
tsdown --minify                # 启用压缩
tsdown --dts                   # 生成声明文件

# 入口选项
tsdown src/index.ts            # 单入口
tsdown src/*.ts                # 通配符模式
tsdown src/a.ts src/b.ts       # 多入口

# 开发
tsdown --watch                 # 监听模式
tsdown --sourcemap             # 生成源码映射
tsdown --clean                 # 清理输出目录

最佳实践

始终为TypeScript库生成类型声明：
```
{ dts: true }
```
外部化依赖以避免打包不必要的代码：
```
{ external: [/^react/, /^@myorg\//] }
```
使用摇树优化以获得最佳包体积：
```
{ treeshake: true }
```
为生产构建启用压缩：
```
{ minify: true }
```

添加垫片以获得更好的ESM/CJS兼容性：

{ shims: true }  // 添加 __dirname, __filename 等

自动生成package.json导出字段：

{ exports: true }  // 创建正确的exports字段

开发时使用监听模式：
```
tsdown --watch
```
为包含许多文件的工具库保留结构：
```
{ unbundle: true }  // 保持目录结构
```

在CI中发布前验证包：

{ publint: 'ci-only', attw: 'ci-only' }

资源

文档: https://tsdown.dev
GitHub: https://github.com/rolldown/tsdown
Rolldown: https://rolldown.rs
迁移指南: https://tsdown.dev/guide/migrate-from-tsup