mediar-ai/tsdown

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

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