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

bash

# 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

typescript

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 [blocked]
Configuration File	Config file formats, multiple configs, workspace	option-config-file [blocked]
CLI Reference	All CLI commands and options	reference-cli [blocked]
Migrate from tsup	Migration guide and compatibility notes	guide-migrate-from-tsup [blocked]
Plugins	Rolldown, Rollup, Unplugin support	advanced-plugins [blocked]

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 [blocked] | | Programmatic API | Build from Node.js scripts | advanced-programmatic [blocked] | | Rolldown Options | Pass options directly to Rolldown | advanced-rolldown-options [blocked] | | CI Environment | CI detection, 'ci-only' / 'local-only' values | advanced-ci [blocked] |

Build Options

Option	Usage	Reference
Entry points	`entry: ['src/.ts', '!/.test.ts']`	option-entry [blocked]
Output formats	`format: ['esm', 'cjs', 'iife', 'umd']`	option-output-format [blocked]
Output directory	`outDir: 'dist'`, `outExtensions`	option-output-directory [blocked]
Type declarations	`dts: true`, `dts: { sourcemap, compilerOptions, vue }`	option-dts [blocked]
Target environment	`target: 'es2020'`, `target: 'esnext'`	option-target [blocked]
Platform	`platform: 'node'`, `platform: 'browser'`	option-platform [blocked]
Tree shaking	`treeshake: true`, custom options	option-tree-shaking [blocked]
Minification	`minify: true`, `minify: 'dce-only'`	option-minification [blocked]
Source maps	`sourcemap: true`, `'inline'`, `'hidden'`	option-sourcemap [blocked]
Watch mode	`watch: true`, watch options	option-watch-mode [blocked]
Cleaning	`clean: true`, clean patterns	option-cleaning [blocked]
Log level	`logLevel: 'silent'`, `failOnWarn: false`	option-log-level [blocked]

Dependency Handling

Feature	Usage	Reference
Never bundle	`deps: { neverBundle: ['react', /^@myorg\//] }`	option-dependencies [blocked]
Always bundle	`deps: { alwaysBundle: ['dep-to-bundle'] }`	option-dependencies [blocked]
Only bundle	`deps: { onlyBundle: ['cac', 'bumpp'] }` - Whitelist	option-dependencies [blocked]
Skip node_modules	`deps: { skipNodeModulesBundle: true }`	option-dependencies [blocked]
Auto external	Automatic dependency/peer/optional externalization	option-dependencies [blocked]

Output Enhancement

Feature	Usage	Reference
Shims	`shims: true` - Add ESM/CJS compatibility	option-shims [blocked]
CJS default	`cjsDefault: true` (default) / `false`	option-cjs-default [blocked]
Package exports	`exports: true` - Generate exports field	option-package-exports [blocked]
CSS handling	[experimental] `css: { ... }` — full pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, code splitting; requires `@tsdown/css`	option-css [blocked]
CSS modules	`css: { modules: { localsConvention: 'camelCase' } }` — scoped class names for `.module.css` files	option-css [blocked]
CSS inject	`css: { inject: true }` — preserve CSS imports in JS output	option-css [blocked]
Unbundle mode	`unbundle: true` - Preserve directory structure	option-unbundle [blocked]
Root directory	`root: 'src'` - Control output directory mapping	option-root [blocked]
Executable	[experimental] `exe: true` - Bundle as standalone executable, cross-platform via `@tsdown/exe`	option-exe [blocked]
Package validation	`publint: true`, `attw: true` - Validate package	option-lint [blocked]

Framework & Runtime Support

Framework	Guide	Reference
React	JSX transform, React Compiler	recipe-react [blocked]
Vue	SFC support, JSX	recipe-vue [blocked]
Solid	SolidJS JSX transform	recipe-solid [blocked]
Svelte	Svelte component libraries (source distribution recommended)	recipe-svelte [blocked]
WASM	WebAssembly modules via `rolldown-plugin-wasm`	recipe-wasm [blocked]

Common Patterns

Basic Library Bundle

typescript

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

Multiple Entry Points

typescript

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)

typescript

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['iife'],
  globalName: 'MyLib',
  platform: 'browser',
  minify: true,
})

React Component Library

typescript

export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  dts: true,
  deps: {
    neverBundle: ['react', 'react-dom'],
  },
  inputOptions: {
    jsx: { runtime: 'automatic' },
  },
})

Preserve Directory Structure

typescript

export default defineConfig({
  entry: ['src/**/*.ts', '!**/*.test.ts'],
  unbundle: true, // Preserve file structure
  format: ['esm'],
  dts: true,
})

CI-Aware Configuration

typescript

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

typescript

import { wasm } from 'rolldown-plugin-wasm'
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [wasm()],
})

Library with CSS and Sass

typescript

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

typescript

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

Cross-Platform Executable (requires `@tsdown/exe`)

typescript

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

typescript

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:

typescript

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:

typescript

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:

typescript

export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
})

CLI Quick Reference

bash

# 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:
typescript
```
{ dts: true }
```

Externalize dependencies to avoid bundling unnecessary code:

typescript

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

Use tree shaking for optimal bundle size:
typescript
```
{ treeshake: true }
```
Enable minification for production builds:
typescript
```
{ minify: true }
```

Add shims for better ESM/CJS compatibility:

typescript

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

Auto-generate package.json exports:

typescript

{ exports: true }  // Creates proper exports field

Use watch mode during development:
bash
```
tsdown --watch
```

Preserve structure for utilities with many files:

typescript

{ unbundle: true }  // Keep directory structure

Validate packages in CI before publishing:

typescript

{ 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

tsdown - The Elegant Library Bundler

Runtime Requirement

When to Use

Quick Start

Basic Configuration

Core References

Build Options

Dependency Handling

Output Enhancement

Framework & Runtime Support

Common Patterns

Basic Library Bundle

Multiple Entry Points

Browser Library (IIFE/UMD)

React Component Library

Preserve Directory Structure

CI-Aware Configuration

WASM Support

Library with CSS and Sass

Standalone Executable

Cross-Platform Executable (requires @tsdown/exe)

Advanced with Hooks

Configuration Features

Multiple Configs

Conditional Config

Workspace/Monorepo

CLI Quick Reference

Best Practices

Resources

Cross-Platform Executable (requires `@tsdown/exe`)