tsdown

name	tsdown
description	Bundle TypeScript and JavaScript libraries with blazing-fast speed powered by Rolldown. Use when building libraries, generating type declarations, bundling for multiple formats, or migrating from tsup.

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

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, in-memory builds (write: false)	advanced-programmatic
Rolldown Options	Pass options directly to Rolldown	advanced-rolldown-options
CI Environment	CI detection, 'ci-only' / 'local-only' values	advanced-ci

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

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: false, suppressWarnings: [...]	option-log-level

Dependency Handling

Feature	Usage	Reference
Never bundle	deps: { neverBundle: ['react', /^@myorg\//] }	option-dependencies
Always bundle	deps: { alwaysBundle: ['dep-to-bundle'] }	option-dependencies
Only bundle	deps: { onlyBundle: ['cac', 'bumpp'] } - Whitelist	option-dependencies
Only import	deps: { onlyImport: ['cac'] } - Whitelist runtime imports in output	option-dependencies
Externalize all	deps: { neverBundle: true }	option-dependencies
Resolve subpaths	deps: { resolveDepSubpath: true } - Resolve external subpath imports (default false)	option-dependencies
Auto external	Automatic dependency/peer/optional 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 - Generate exports field	option-package-exports
CSS handling	[experimental] css: { ... } — full pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, code splitting; requires @tsdown/css	option-css
CSS modules	css: { modules: { localsConvention: 'camelCase' } } — scoped class names for .module.css files	option-css
CSS inject	css: { inject: true } — preserve CSS imports in JS output	option-css
Copy files	copy: 'public' or copy: { from, to, flatten, rename } - Copy static assets to output	option-copy
Unbundle mode	unbundle: true - Preserve directory structure	option-unbundle
Root directory	root: 'src' - Control output directory mapping	option-root
Executable	[experimental] exe: true - Bundle as standalone executable, cross-platform via @tsdown/exe	option-exe
Package validation	publint: true, attw: true - Validate package	option-lint

Framework & Runtime Support

Framework	Guide	Reference
React	JSX transform, React Compiler	recipe-react
Vue	SFC support, JSX	recipe-vue
Solid	SolidJS JSX transform	recipe-solid
Svelte	Svelte component libraries (source distribution recommended)	recipe-svelte
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,
  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' },
    ],