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](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/guide-getting-started.md)

Configuration File
Config file formats, multiple configs, workspace
[option-config-file](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-config-file.md)

CLI Reference
All CLI commands and options
[reference-cli](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/reference-cli.md)

Migrate from tsup
Migration guide and compatibility notes
[guide-migrate-from-tsup](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/guide-migrate-from-tsup.md)

Plugins
Rolldown, Rollup, Unplugin support
[advanced-plugins](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/advanced-plugins.md)

Hooks
Lifecycle hooks for custom logic
[advanced-hooks](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/advanced-hooks.md)

Programmatic API
Build from Node.js scripts
[advanced-programmatic](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/advanced-programmatic.md)

Rolldown Options
Pass options directly to Rolldown
[advanced-rolldown-options](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/advanced-rolldown-options.md)

CI Environment
CI detection, `'ci-only'` / `'local-only'` values
[advanced-ci](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/advanced-ci.md)

## Build Options

Option
Usage
Reference

Entry points
`entry: ['src/*.ts', '!**/*.test.ts']`
[option-entry](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-entry.md)

Output formats
`format: ['esm', 'cjs', 'iife', 'umd']`
[option-output-format](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-output-format.md)

Output directory
`outDir: 'dist'`, `outExtensions`
[option-output-directory](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-output-directory.md)

Type declarations
`dts: true`, `dts: { sourcemap, compilerOptions, vue }`
[option-dts](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-dts.md)

Target environment
`target: 'es2020'`, `target: 'esnext'`
[option-target](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-target.md)

Platform
`platform: 'node'`, `platform: 'browser'`
[option-platform](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-platform.md)

Tree shaking
`treeshake: true`, custom options
[option-tree-shaking](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-tree-shaking.md)

Minification
`minify: true`, `minify: 'dce-only'`
[option-minification](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-minification.md)

Source maps
`sourcemap: true`, `'inline'`, `'hidden'`
[option-sourcemap](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-sourcemap.md)

Watch mode
`watch: true`, watch options
[option-watch-mode](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-watch-mode.md)

Cleaning
`clean: true`, clean patterns
[option-cleaning](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-cleaning.md)

Log level
`logLevel: 'silent'`, `failOnWarn: 'ci-only'`
[option-log-level](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-log-level.md)

## Dependency Handling

Feature
Usage
Reference

Never bundle
`deps: { neverBundle: ['react', /^@myorg\//] }`
[option-dependencies](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-dependencies.md)

Always bundle
`deps: { alwaysBundle: ['dep-to-bundle'] }`
[option-dependencies](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-dependencies.md)

Only allow bundle
`deps: { onlyAllowBundle: ['cac', 'bumpp'] }` - Whitelist
[option-dependencies](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-dependencies.md)

Skip node_modules
`deps: { skipNodeModulesBundle: true }`
[option-dependencies](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-dependencies.md)

Auto external
Automatic peer/dependency externalization
[option-dependencies](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-dependencies.md)

## Output Enhancement

Feature
Usage
Reference

Shims
`shims: true` - Add ESM/CJS compatibility
[option-shims](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-shims.md)

CJS default
`cjsDefault: true` (default) / `false`
[option-cjs-default](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-cjs-default.md)

Package exports
`exports: true` - Auto-generate exports field
[option-package-exports](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-package-exports.md)

CSS handling
**[experimental]** Still in development
[option-css](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-css.md)

Unbundle mode
`unbundle: true` - Preserve directory structure
[option-unbundle](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-unbundle.md)

Executable (SEA)
**[experimental]** `exe: true` - Bundle as Node.js SEA executable
[option-exe](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-exe.md)

Package validation
`publint: true`, `attw: true` - Validate package
[option-lint](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/option-lint.md)

## Framework & Runtime Support

Framework
Guide
Reference

React
JSX transform, Fast Refresh
[recipe-react](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/recipe-react.md)

Vue
SFC support, JSX
[recipe-vue](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/recipe-vue.md)

WASM
WebAssembly modules via `rolldown-plugin-wasm`
[recipe-wasm](https://github.com/hairyf/skills/blob/HEAD/skills/tsdown/references/recipe-wasm.md)

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

deps: {

neverBundle: ['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()],

})

### Node.js Executable (SEA)

export default defineConfig({

entry: ['src/cli.ts'],

exe: true,

})

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

tsdown --exe # Bundle as executable (SEA)

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:

{ deps: { neverBundle: [/^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' }