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,                  // 构建前清理输出目录
})

核心参考文档

构建选项

依赖处理

输出增强

框架与运行时支持

常用模式

基础库打包

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

多入口点

export default defineConfig({
  entry: {
    index: 'src/index.ts',   // 输出 dist/index.js
    utils: 'src/utils.ts',   // 输出 dist/utils.js
    cli: 'src/cli.ts',       // 输出 dist/cli.js
  },
  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'],      // 支持 TSX
  format: ['esm', 'cjs'],
  dts: true,
  external: ['react', 'react-dom'],  // 不打包 React
  plugins: [
    // React Fast Refresh 支持（开发环境下）
  ],
})

保留目录结构

export default defineConfig({
  entry: ['src/**/*.ts', '!**/*.test.ts'],  // 匹配所有 ts 文件，排除测试文件
  unbundle: true, // 保留文件结构
  format: ['esm'],
  dts: true,
})

CI 环境感知配置

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  failOnWarn: 'ci-only',   // 仅在 CI 环境中将警告视为错误
  publint: 'ci-only',       // 仅在 CI 环境中运行 publint
  attw: 'ci-only',           // 仅在 CI 环境中运行 @arethetypeswrong
})

WASM 支持

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

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [wasm()],  // 添加 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,       // 开发环境生成 sourcemap
  }
})

工作区/Monorepo 支持

使用 glob 模式构建多个包：

export default defineConfig({
  workspace: 'packages/*',  // 匹配所有 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                # 使用 glob 模式
tsdown src/a.ts src/b.ts       # 指定多个入口

# 开发
tsdown --watch                 # 监听模式
tsdown --sourcemap             # 生成 source maps
tsdown --clean                 # 构建前清理输出目录

最佳实践

1. 始终为 TypeScript 库生成类型声明文件：

   { dts: true }
   

2. 外部化依赖 以避免打包不必要的代码：

   { external: [/^react/, /^@myorg\//] }
   

3. 启用摇树优化 以获得最佳包体积：

   { treeshake: true }
   

4. 为生产构建启用代码压缩：

   { minify: true }
   

5. 添加 shims 以获得更好的 ESM/CJS 兼容性：

   { shims: true }  // 添加 __dirname, __filename 等 Node.js 全局变量
   

6. 自动生成 package.json 的 exports 字段：

   { exports: true }  // 自动创建符合规范的 exports 字段
   

7. 开发时使用监听模式：

   tsdown --watch
   

8. 对于包含多个文件的工具库，保留目录结构：

   { unbundle: true }  // 保留原始目录结构
   

9. 在 CI 中发布前验证包：

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

资源

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