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

bash

# 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	`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

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	[experimental] Still in development	option-css
Unbundle mode	`unbundle: true` - Preserve directory structure	option-unbundle
Package validation	`publint: true`, `attw: true` - Validate package	option-lint

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

bash

# 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:
ts
```
{ dts: true }
```
•
Externalize dependencies to avoid bundling unnecessary code:
ts
```
{ external: [/^react/, /^@myorg\//] }
```
•
Use tree shaking for optimal bundle size:
ts
```
{ treeshake: true }
```
•
Enable minification for production builds:
ts
```
{ 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

•
Use watch mode during development:
bash
```
tsdown --watch
```
•
Preserve structure for utilities with many files:
ts
```
{ unbundle: true }  // Keep directory structure
```
•
Validate packages in CI before publishing:
ts
```
{ publint: 'ci-only', attw: 'ci-only' }
```

Resources

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