tsdown - The Elegant Library Bundler

Blazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.

Runtime Requirement

tsdown requires Node.js 22.18.0 or higher to run (build-time only). However, the bundled output can target much lower Node.js versions via the target [blocked] option, so libraries built with tsdown are not locked to Node.js 22+ at runtime.

If your package needs to support Node.js 18 / 20:

• Build with Node.js 22+ in CI (e.g. set target: 'node18' or target: 'node20').
• Test the built output (or the packed tarball) on the lower Node.js versions you intend to support — e.g. using a matrix job that runs the published package's tests on Node.js 18 / 20 / 22.

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

# Installpnpm add -D tsdown
# Basic usagenpx tsdown
# With config filenpx tsdown --config tsdown.config.ts
# Watch modenpx tsdown --watch
# Migrate from tsupnpx tsdown-migrate

Basic Configuration

import { defineConfig } from 'tsdown'
export default defineConfig({  entry: ['./src/index.ts'],  format: ['esm', 'cjs'],  dts: true,  clean: true,})

Core References

For comprehensive migration assistance with complete option mappings, install the dedicated tsdown-migrate skill: npx skills add rolldown/tsdown --skill tsdown-migrate

Build Options

Dependency Handling

Output Enhancement

Framework & Runtime Support

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'],  },  inputOptions: {    jsx: { runtime: 'automatic' },  },})

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',  // opt-in: fail on warnings in CI  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()],})

Library with CSS and Sass

export default defineConfig({  entry: ['src/index.ts'],  format: ['esm', 'cjs'],  dts: true,  target: 'chrome100',  css: {    preprocessorOptions: {      scss: {        additionalData: `@use "src/styles/variables" as *;`,      },    },  },})

Standalone Executable

export default defineConfig({  entry: ['src/cli.ts'],  exe: true,})

Cross-Platform Executable (requires @tsdown/exe)

export default defineConfig({  entry: ['src/cli.ts'],  exe: {    targets: [      { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },      { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },      { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },    ],  },})

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 commandstsdown                          # Build oncetsdown --watch                  # Watch modetsdown --config custom.ts       # Custom confignpx tsdown-migrate              # Migrate from tsup
# Output optionstsdown --format esm,cjs        # Multiple formatstsdown -d lib                  # Custom output directory (--out-dir)tsdown --minify                # Enable minificationtsdown --dts                   # Generate declarationstsdown --exe                   # Bundle as standalone executabletsdown --unbundle              # Bundleless modetsdown --copy public           # Copy static files to output
# Entry optionstsdown src/index.ts            # Single entrytsdown src/*.ts                # Glob patternstsdown src/a.ts src/b.ts       # Multiple entries
# Workspace / Monorepotsdown -W                      # Enable workspace modetsdown -W -F my-package        # Filter specific packagetsdown --filter /^pkg-/        # Filter by regextsdown -W --concurrency 4      # Limit parallel Rolldown builds
# Developmenttsdown --watch                 # Watch modetsdown --sourcemap             # Generate source mapstsdown --clean                 # Clean output directorytsdown --from-vite             # Reuse Vite configtsdown --tsconfig tsconfig.build.json  # Custom tsconfig

Best Practices

1. Always generate type declarations for TypeScript libraries:

   ts

   { dts: true }

2. Externalize dependencies to avoid bundling unnecessary code:

   ts

   { deps: { neverBundle: [/^react/, /^@myorg\//] } }

3. Use tree shaking for optimal bundle size:

   ts

   { treeshake: true }

4. Enable minification for production builds:

   ts

   { minify: true }

5. Add shims for better ESM/CJS compatibility:

   ts

   { shims: true }  // Adds __dirname, __filename, etc.

6. Auto-generate package.json exports:

   ts

   { exports: true }  // Creates proper exports field

7. Use watch mode during development:

   bash

   tsdown --watch

8. Preserve structure for utilities with many files:

   ts

   { unbundle: true }  // Keep directory structure

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