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

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

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' }

Resources

• Documentation: https://tsdown.dev

• GitHub: https://github.com/rolldown/tsdown

• Rolldown: https://rolldown.rs

• Migration Guide: https://tsdown.dev/guide/migrate-from-tsup