Back to Details

tsdown

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

tsdown - The Elegant Library Bundler

tsdown - 优雅的库打包工具

Blazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.
由Rolldown和Oxc驱动的、速度极快的TypeScript/JavaScript库打包工具。

When to Use

适用场景

  • Building TypeScript/JavaScript libraries for npm
  • Generating TypeScript declaration files (.d.ts)
  • Bundling for multiple formats (ESM, CJS, IIFE, UMD)
  • Optimizing bundles with tree shaking and minification
  • Migrating from tsup with minimal changes
  • Building React, Vue, Solid, or Svelte component libraries
  • 为npm构建TypeScript/JavaScript库
  • 生成TypeScript声明文件（.d.ts）
  • 打包为多种格式（ESM、CJS、IIFE、UMD）
  • 通过Tree Shaking和代码压缩优化包体积
  • 从tsup迁移，只需少量改动
  • 构建React、Vue、Solid或Svelte组件库

Quick Start

快速开始

bash
undefined
bash
undefined

Install

安装

pnpm add -D tsdown
pnpm add -D tsdown

Basic usage

基础用法

npx tsdown
npx tsdown

With config file

使用配置文件

npx tsdown --config tsdown.config.ts
npx tsdown --config tsdown.config.ts

Watch mode

监听模式

npx tsdown --watch
npx tsdown --watch

Migrate from tsup

从tsup迁移

npx tsdown-migrate
undefined
npx tsdown-migrate
undefined

Basic Configuration

基础配置

ts
import { defineConfig } from 'tsdown'

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

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

Core References

核心参考

TopicDescriptionReference
Getting StartedInstallation, first bundle, CLI basicsguide-getting-started
Configuration FileConfig file formats, multiple configs, workspaceoption-config-file
CLI ReferenceAll CLI commands and optionsreference-cli
Migrate from tsupMigration guide and compatibility notesguide-migrate-from-tsup
PluginsRolldown, Rollup, Unplugin supportadvanced-plugins
HooksLifecycle hooks for custom logicadvanced-hooks
Programmatic APIBuild from Node.js scriptsadvanced-programmatic
Rolldown OptionsPass options directly to Rolldownadvanced-rolldown-options
CI EnvironmentCI detection, 
'ci-only'
/ 
'local-only'
values		advanced-ci
主题描述参考链接
快速入门安装、首次打包、CLI基础guide-getting-started
配置文件配置文件格式、多配置、工作区option-config-file
CLI参考所有CLI命令和选项reference-cli
从tsup迁移迁移指南和兼容性说明guide-migrate-from-tsup
插件支持Rolldown、Rollup、Unpluginadvanced-plugins
钩子用于自定义逻辑的生命周期钩子advanced-hooks
程序化API通过Node.js脚本构建advanced-programmatic
Rolldown选项直接传递选项给Rolldownadvanced-rolldown-options
CI环境CI检测、'ci-only'/'local-only'参数advanced-ci

Build Options

构建选项

OptionUsageReference
Entry points
entry: ['src/*.ts', '!**/*.test.ts']
option-entry
Output formats
format: ['esm', 'cjs', 'iife', 'umd']
option-output-format
Output directory
outDir: 'dist'
, 
outExtensions
option-output-directory
Type declarations
dts: true
, 
dts: { sourcemap, compilerOptions, vue }
option-dts
Target environment
target: 'es2020'
, 
target: 'esnext'
option-target
Platform
platform: 'node'
, 
platform: 'browser'
option-platform
Tree shaking
treeshake: true
, custom options		option-tree-shaking
Minification
minify: true
, 
minify: 'dce-only'
option-minification
Source maps
sourcemap: true
, 
'inline'
, 
'hidden'
option-sourcemap
Watch mode
watch: true
, watch options		option-watch-mode
Cleaning
clean: true
, clean patterns		option-cleaning
Log level
logLevel: 'silent'
, 
failOnWarn: 'ci-only'
option-log-level
选项用法参考链接
入口文件
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
Tree Shaking
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

Dependency Handling

依赖处理

FeatureUsageReference
External deps
external: ['react', /^@myorg\//]
option-dependencies
Inline deps
noExternal: ['dep-to-bundle']
option-dependencies
Auto externalAutomatic peer/dependency externalizationoption-dependencies
特性用法参考链接
外部依赖
external: ['react', /^@myorg\//]
option-dependencies
内联依赖
noExternal: ['dep-to-bundle']
option-dependencies
自动外部化自动将peer依赖/依赖设为外部option-dependencies

Output Enhancement

输出增强

FeatureUsageReference
Shims
shims: true
- Add ESM/CJS compatibility		option-shims
CJS default
cjsDefault: true
(default) / 
false
option-cjs-default
Package exports
exports: true
- Auto-generate exports field		option-package-exports
CSS handling[experimental] Still in developmentoption-css
Unbundle mode
unbundle: true
- Preserve directory structure		option-unbundle
Package validation
publint: true
, 
attw: true
- Validate package		option-lint
特性用法参考链接
兼容性垫片
shims: true
- 添加ESM/CJS兼容性支持		option-shims
CJS默认导出
cjsDefault: true
（默认）/ 
false
option-cjs-default
Package导出
exports: true
- 自动生成exports字段		option-package-exports
CSS处理[实验性] 仍在开发中option-css
非打包模式
unbundle: true
- 保留目录结构		option-unbundle
包验证
publint: true
, 
attw: true
- 验证包的有效性		option-lint

Framework & Runtime Support

框架与运行时支持

FrameworkGuideReference
ReactJSX transform, Fast Refreshrecipe-react
VueSFC support, JSXrecipe-vue
WASMWebAssembly modules via 
rolldown-plugin-wasm
recipe-wasm
框架指南参考链接
ReactJSX转换、Fast Refreshrecipe-react
VueSFC支持、JSXrecipe-vue
WASM通过
rolldown-plugin-wasm
支持WebAssembly模块		recipe-wasm

Common Patterns

常见配置示例

Basic Library Bundle

基础库打包

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

Multiple Entry Points

多入口文件

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

Browser Library (IIFE/UMD)

浏览器端库（IIFE/UMD）

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

React Component Library

React组件库

ts
export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  dts: true,
  external: ['react', 'react-dom'],
  plugins: [
    // React Fast Refresh support
  ],
})
ts
export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  dts: true,
  external: ['react', 'react-dom'],
  plugins: [
    // React Fast Refresh支持
  ],
})

Preserve Directory Structure

保留目录结构

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

CI-Aware Configuration

感知CI环境的配置

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

WASM Support

WASM支持

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

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [wasm()],
})
ts
import { wasm } from 'rolldown-plugin-wasm'
import { defineConfig } from 'tsdown'

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

Advanced with Hooks

钩子进阶用法

ts
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!')
    },
  },
})
ts
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('构建完成！')
    },
  },
})

Configuration Features

配置特性

Multiple Configs

多配置

Export an array for multiple build configurations:
ts
export default defineConfig([
  {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    dts: true,
  },
  {
    entry: ['src/cli.ts'],
    format: ['esm'],
    platform: 'node',
  },
])
导出数组以使用多个构建配置：
ts
export default defineConfig([
  {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    dts: true,
  },
  {
    entry: ['src/cli.ts'],
    format: ['esm'],
    platform: 'node',
  },
])

Conditional Config

条件配置

Use functions for dynamic configuration:
ts
export default defineConfig((options) => {
  const isDev = options.watch
  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
  }
})
使用函数实现动态配置：
ts
export default defineConfig((options) => {
  const isDev = options.watch
  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
  }
})

Workspace/Monorepo

工作区/单体仓库

Use glob patterns to build multiple packages:
ts
export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
})
使用通配符模式构建多个包：
ts
export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
})

CLI Quick Reference

CLI快速参考

bash
undefined
bash
undefined

Basic commands

基础命令

tsdown # Build once tsdown --watch # Watch mode tsdown --config custom.ts # Custom config npx tsdown-migrate # Migrate from tsup
tsdown # 单次构建 tsdown --watch # 监听模式 tsdown --config custom.ts # 使用自定义配置 npx tsdown-migrate # 从tsup迁移

Output options

输出选项

tsdown --format esm,cjs # Multiple formats tsdown --outDir lib # Custom output directory tsdown --minify # Enable minification tsdown --dts # Generate declarations
tsdown --format esm,cjs # 多种格式 tsdown --outDir lib # 自定义输出目录 tsdown --minify # 启用代码压缩 tsdown --dts # 生成类型声明

Entry options

入口选项

tsdown src/index.ts # Single entry tsdown src/*.ts # Glob patterns tsdown src/a.ts src/b.ts # Multiple entries
tsdown src/index.ts # 单个入口 tsdown src/*.ts # 通配符模式 tsdown src/a.ts src/b.ts # 多个入口

Development

开发相关

tsdown --watch # Watch mode tsdown --sourcemap # Generate source maps tsdown --clean # Clean output directory
undefined
tsdown --watch # 监听模式 tsdown --sourcemap # 生成源映射 tsdown --clean # 清理输出目录
undefined

Best Practices

最佳实践

  1. Always generate type declarations for TypeScript libraries:
    ts
    { dts: true }
  2. Externalize dependencies to avoid bundling unnecessary code:
    ts
    { external: [/^react/, /^@myorg\//] }
  3. Use tree shaking for optimal bundle size:
    ts
    { treeshake: true }
  4. Enable minification for production builds:
    ts
    { minify: true }
  5. Add shims for better ESM/CJS compatibility:
    ts
    { shims: true }  // Adds __dirname, __filename, etc.
  6. Auto-generate package.json exports:
    ts
    { exports: true }  // Creates proper exports field
  7. Use watch mode during development:
    bash
    tsdown --watch
  8. Preserve structure for utilities with many files:
    ts
    { unbundle: true }  // Keep directory structure
  9. Validate packages in CI before publishing:
    ts
    { publint: 'ci-only', attw: 'ci-only' }
  1. 始终为TypeScript库生成类型声明：
    ts
    { dts: true }
  2. 将依赖设为外部，避免打包不必要的代码：
    ts
    { external: [/^react/, /^@myorg\//] }
  3. 启用Tree Shaking以优化包体积：
    ts
    { treeshake: true }
  4. 为生产构建启用代码压缩：
    ts
    { minify: true }
  5. 添加兼容性垫片以提升ESM/CJS兼容性：
    ts
    { shims: true }  // 添加__dirname、__filename等变量
  6. 自动生成package.json的exports字段：
    ts
    { exports: true }  // 创建规范的exports字段
  7. 开发时使用监听模式：
    bash
    tsdown --watch
  8. 对于包含多个文件的工具库，保留目录结构：
    ts
    { unbundle: true }  // 保持目录结构
  9. 在CI环境中验证包后再发布：
    ts
    { publint: 'ci-only', attw: 'ci-only' }

Resources

相关资源