tsdown

tsdown - 优雅的库打包工具

由 Rolldown 和 Oxc 驱动的超高速 TypeScript/JavaScript 库打包工具。

运行时要求

tsdown 需要 Node.js 22.18.0 或更高版本才能运行（仅限构建时）。不过，通过 target 选项，打包后的输出可以面向更低版本的 Node.js，因此使用 tsdown 构建的库在运行时不受 Node.js 22+ 的限制。

如果你的软件包需要支持 Node.js 18 / 20：

• 在 CI 中使用 Node.js 22+ 进行构建（例如设置 target: 'node18' 或 target: 'node20'）。
• 在你计划支持的较低版本 Node.js 上测试构建输出（或打包后的 tarball）——例如，使用矩阵任务在 Node.js 18 / 20 / 22 上运行已发布软件包的测试。

适用场景

• 为 npm 构建 TypeScript/JavaScript 库
• 生成 TypeScript 声明文件（.d.ts）
• 打包为多种格式（ESM、CJS、IIFE、UMD）
• 使用摇树优化和压缩优化打包结果
• 以最少的改动从 tsup 迁移
• 构建 React、Vue、Solid 或 Svelte 组件库

快速开始

# Install
pnpm add -D tsdown

# Basic usage
npx tsdown

# With config file
npx tsdown --config tsdown.config.ts

# Watch mode
npx tsdown --watch

# Migrate from 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 脚本构建、内存构建（write: false）	advanced-programmatic
Rolldown 选项	直接向 Rolldown 传递选项	advanced-rolldown-options
CI 环境	CI 检测、'ci-only' / 'local-only' 值	advanced-ci

如需全面的迁移协助和完整的选项映射，请安装专用的 tsdown-migrate 技能：npx skills add rolldown/tsdown --skill tsdown-migrate

构建选项

选项	用法	参考
入口点	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: false、suppressWarnings: [...]	option-log-level

依赖处理

功能	用法	参考
永不打包	deps: { neverBundle: ['react', /^@myorg\//] }	option-dependencies
始终打包	deps: { alwaysBundle: ['dep-to-bundle'] }	option-dependencies
仅打包	deps: { onlyBundle: ['cac', 'bumpp'] } - 白名单	option-dependencies
仅导入	deps: { onlyImport: ['cac'] } - 输出中的运行时导入白名单	option-dependencies
全部外置	deps: { neverBundle: true }	option-dependencies
解析子路径	deps: { resolveDepSubpath: true } - 解析外部子路径导入（默认值为 false）	option-dependencies
自动外置	自动外置依赖、对等依赖和可选依赖	option-dependencies

输出增强

功能	用法	参考
垫片	shims: true - 添加 ESM/CJS 兼容性	option-shims
CJS 默认导出	cjsDefault: true（默认值）/ false	option-cjs-default
包导出	exports: true - 生成 exports 字段	option-package-exports
CSS 处理	[实验性] css: { ... } — 提供包含预处理器、Lightning CSS、PostCSS、CSS 模块和代码拆分的完整流水线；需要 @tsdown/css	option-css
CSS 模块	css: { modules: { localsConvention: 'camelCase' } } — 为 .module.css 文件生成作用域类名	option-css
注入 CSS	css: { inject: true } — 在 JS 输出中保留 CSS 导入	option-css
复制文件	copy: 'public' 或 copy: { from, to, flatten, rename } - 将静态资源复制到输出目录	option-copy
非打包模式	unbundle: true - 保留目录结构	option-unbundle
根目录	root: 'src' - 控制输出目录映射	option-root
可执行文件	[实验性] exe: true - 打包为独立可执行文件，通过 @tsdown/exe 支持跨平台	option-exe
包验证	publint: true、attw: true - 验证包	option-lint

框架和运行时支持

框架	指南	参考
React	JSX 转换、React Compiler	recipe-react
Vue	SFC 支持、JSX	recipe-vue
Solid	SolidJS JSX 转换	recipe-solid
Svelte	Svelte 组件库（推荐源码分发）	recipe-svelte
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,
  deps: {
    neverBundle: ['react', 'react-dom'],
  },
  inputOptions: {
    jsx: { runtime: 'automatic' },
  },
})

保留目录结构

export default defineConfig({
  entry: ['src/**/*.ts', '!**/*.test.ts'],
  unbundle: true, // Preserve file structure
  format: ['esm'],
  dts: true,
})

CI 感知配置

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  failOnWarn: 'ci-only',  // opt-in: fail on warnings in CI
  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()],
})

包含 CSS 和 Sass 的库

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  target: 'chrome100',
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "src/styles/variables" as *;`,
      },
    },
  },
})

独立可执行文件

export default defineConfig({
  entry: ['src/cli.ts'],
  exe: true,
})

跨平台可执行文件（需要 @tsdown/exe）

export default defineConfig({
  entry: ['src/cli.ts'],
  exe: {
    targets: [
      { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },
      { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },
      { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },
    ],
  },
})

使用钩子的高级配置

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

配置功能

多个配置

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

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,
  }
})

工作区/Monorepo

使用 glob 模式构建多个包：

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

CLI 快速参考

# Basic commands
tsdown                          # Build once
tsdown --watch                  # Watch mode
tsdown --config custom.ts       # Custom config
npx tsdown-migrate              # Migrate from tsup

# Output options
tsdown --format esm,cjs        # Multiple formats
tsdown -d lib                  # Custom output directory (--out-dir)
tsdown --minify                # Enable minification
tsdown --dts                   # Generate declarations
tsdown --exe                   # Bundle as standalone executable
tsdown --unbundle              # Bundleless mode
tsdown --copy public           # Copy static files to output

# Entry options
tsdown src/index.ts            # Single entry
tsdown src/*.ts                # Glob patterns
tsdown src/a.ts src/b.ts       # Multiple entries

# Workspace / Monorepo
tsdown -W                      # Enable workspace mode
tsdown -W -F my-package        # Filter specific package
tsdown --filter /^pkg-/        # Filter by regex
tsdown -W --concurrency 4      # Limit parallel Rolldown builds

# Development
tsdown --watch                 # Watch mode
tsdown --sourcemap             # Generate source maps
tsdown --clean                 # Clean output directory
tsdown --from-vite             # Reuse Vite config
tsdown --tsconfig tsconfig.build.json  # Custom tsconfig

最佳实践

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

   { dts: true }
   

2. 将依赖项设为外部依赖，避免打包不必要的代码：

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

3. 使用 tree shaking，优化打包体积：

   { treeshake: true }
   

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

   { minify: true }
   

5. 添加 shim，提高 ESM/CJS 兼容性：

   { shims: true }  // Adds __dirname, __filename, etc.
   

6. 自动生成 package.json 导出配置：

   { exports: true }  // Creates proper exports field
   

7. 在开发期间使用监视模式：

   tsdown --watch
   

8. 为包含许多文件的工具保留目录结构：

   { unbundle: true }  // Keep directory structure
   

9. 在发布前于 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