tsdown - 极速TypeScript/JavaScript库打包工具，基于Rolldown和Oxc

tsdown by antfu/skills

4,400 周安装量

4,300 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/antfu/skills --skill tsdown

开发开发运维

🇨🇳中文介绍

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 基础

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

选项	用法	参考链接
入口点	`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,
})

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

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

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

# 基本命令
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' }

🇺🇸English

tsdown - The Elegant Library Bundler

Blazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.

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

Quick Start

# 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

Basic Configuration

import { defineConfig } from 'tsdown'

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

Core References

Topic	Description	Reference
Getting Started	Installation, first bundle, CLI basics	guide-getting-started
Configuration File	Config file formats, multiple configs, workspace	option-config-file
CLI Reference	All CLI commands and options	reference-cli
Migrate from tsup	Migration guide and compatibility notes	guide-migrate-from-tsup
Plugins	Rolldown, Rollup, Unplugin support	advanced-plugins
Hooks	Lifecycle hooks for custom logic	advanced-hooks
Programmatic API	Build from Node.js scripts	advanced-programmatic
Rolldown Options	Pass options directly to Rolldown	advanced-rolldown-options
CI Environment	CI detection, `'ci-only'` / `'local-only'` values	advanced-ci

Build Options

Option	Usage	Reference
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

Dependency Handling

Feature	Usage	Reference
External deps	`external: ['react', /^@myorg\//]`	option-dependencies
Inline deps	`noExternal: ['dep-to-bundle']`	option-dependencies
Auto external	Automatic peer/dependency externalization	option-dependencies

Output Enhancement

Feature	Usage	Reference
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	Still in development

Framework & Runtime Support

Framework	Guide	Reference
React	JSX transform, Fast Refresh	recipe-react
Vue	SFC support, JSX	recipe-vue
WASM	WebAssembly modules via `rolldown-plugin-wasm`	recipe-wasm

Common Patterns

Basic Library Bundle

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

Multiple Entry Points

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)

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

React Component Library

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

Preserve Directory Structure

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

CI-Aware Configuration

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

WASM Support

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

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

Advanced with Hooks

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

Configuration Features

Multiple Configs

Export an array for multiple build configurations:

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:

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:

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

CLI Quick Reference

# 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 --outDir lib            # Custom output directory
tsdown --minify                # Enable minification
tsdown --dts                   # Generate declarations

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

# Development
tsdown --watch                 # Watch mode
tsdown --sourcemap             # Generate source maps
tsdown --clean                 # Clean output directory

Best Practices

Always generate type declarations for TypeScript libraries:
```
{ dts: true }
```
Externalize dependencies to avoid bundling unnecessary code:
```
{ external: [/^react/, /^@myorg\//] }
```
Use tree shaking for optimal bundle size:
```
{ treeshake: true }
```
Enable minification for production builds:
```
{ minify: true }
```

Add shims for better ESM/CJS compatibility:

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

Auto-generate package.json exports :

{ exports: true }  // Creates proper exports field

Resources

Documentation: https://tsdown.dev
GitHub: https://github.com/rolldown/tsdown
Rolldown: https://rolldown.rs
Migration Guide: https://tsdown.dev/guide/migrate-from-tsup

Weekly Installs

3.5K

Repository

antfu/skills

GitHub Stars

3.9K

First Seen

Jan 28, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode2.7K

codex2.6K

gemini-cli2.6K

github-copilot2.5K

cursor2.4K

claude-code2.3K

Use watch mode during development:

tsdown --watch

Preserve structure for utilities with many files:

{ unbundle: true }  // Keep directory structure

Validate packages in CI before publishing:

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

tsdown - 极速TypeScript/JavaScript库打包工具，基于Rolldown和Oxc

🇨🇳中文介绍

tsdown - 优雅的库打包工具

适用场景

快速开始

基本配置

核心参考

相关 Skills

构建选项

依赖处理

输出增强