tsdown - The Elegant Library Bundler

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

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

Build Options

Dependency Handling

Output Enhancement

Framework & Runtime Support

Common Patterns

Basic Library Bundle

Copy
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

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

Conditional Config

Copy
export default defineConfig((options) => {
  const isDev = options.watch
  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
  }
})

Workspace/Monorepo

Copy
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

1. Always generate type declarations for TypeScript libraries:
   { dts: true }
2. Externalize dependencies to avoid bundling unnecessary code:
   { external: [/^react/, /^@myorg\//] }
3. Use tree shaking for optimal bundle size:
   { treeshake: true }
4. Enable minification for production builds:
   { minify: true }
5. Add shims for better ESM/CJS compatibility:
   { shims: true } // Adds __dirname, __filename, etc.
6. Auto-generate package.json exports:
   { exports: true } // Creates proper exports field
7. Use watch mode during development:
   tsdown --watch
8. Preserve structure for utilities with many files:
   { unbundle: true } // Keep directory structure
9. 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