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

# 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

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

| 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

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 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 -d lib                  # Custom output directory (--out-dir)

tsdown --minify                # Enable minification

tsdown --dts                   # Generate declarations

tsdown --exe                   # Bundle as standalone executable

tsdown --unbundle              # Bundleless mode

# Entry options

tsdown src/index.ts            # Single entry

tsdown src/*.ts                # Glob patterns

tsdown src/a.ts src/b.ts       # Multiple entries

# Workspace / Monorepo

tsdown -W                      # Enable workspace mode

tsdown -W -F my-package        # Filter specific package

tsdown --filter /^pkg-/        # Filter by regex

# Development

tsdown --watch                 # Watch mode

tsdown --sourcemap             # Generate source maps

tsdown --clean                 # Clean output directory

tsdown --from-vite             # Reuse Vite config

tsdown --tsconfig tsconfig.build.json  # Custom tsconfig

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

Resources

• Documentation: https://tsdown.dev

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

• Rolldown: https://rolldown.rs

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