antfu avatar
4.1k

tsdown is a high-performance library bundler designed for TypeScript and JavaScript projects, especially for building npm libraries, component libraries (React, Vue, Svelte, Solid), and generating type declaration files. It offers versatile features like multi-format bundling, tree-shaking, minification, and support for various frameworks and runtime environments, making it suitable for developers seeking an efficient, flexible bundling solution with minimal migration effort. Key capabilities include configuration via files or CLI, dependency management, output enhancements, and advanced plugin support.

npx skills add https://github.com/antfu/skills --skill 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: false 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 Skip node_modules deps: { skipNodeModulesBundle: true } 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] css: { ... } — full pipeline with preprocessors, Lightning CSS, PostCSS, code splitting; requires @tsdown/css option-css CSS inject css: { inject: true } — preserve CSS imports in JS output option-css 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' },
    ],
  },
})

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

  1. Always generate type declarations for TypeScript libraries: 
    { dts: true }
  2. Externalize dependencies to avoid bundling unnecessary code: 
    { deps: { neverBundle: [/^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

GitHub Owner

Owner: antfu

GitHub Links

Files

guide-getting-started

option-config-file

reference-cli

guide-migrate-from-tsup

advanced-plugins

advanced-hooks

advanced-programmatic

advanced-rolldown-options

advanced-ci

option-entry

option-output-format

option-output-directory

option-dts

option-target

option-platform

option-tree-shaking

option-minification

option-sourcemap

option-watch-mode

option-cleaning

option-log-level

option-dependencies

option-dependencies

option-dependencies

option-dependencies

option-dependencies

option-shims

option-cjs-default

option-package-exports

option-css

option-css

option-unbundle

option-root

option-exe

option-lint

recipe-react

recipe-vue

recipe-solid

recipe-svelte

recipe-wasm

SKILL.md

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.

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

TopicDescriptionReference
Getting StartedInstallation, first bundle, CLI basicsguide-getting-started
Configuration FileConfig file formats, multiple configs, workspaceoption-config-file
CLI ReferenceAll CLI commands and optionsreference-cli
Migrate from tsupMigration guide and compatibility notesguide-migrate-from-tsup
PluginsRolldown, Rollup, Unplugin supportadvanced-plugins
HooksLifecycle hooks for custom logicadvanced-hooks
Programmatic APIBuild from Node.js scriptsadvanced-programmatic
Rolldown OptionsPass options directly to Rolldownadvanced-rolldown-options
CI EnvironmentCI detection, 'ci-only' / 'local-only' valuesadvanced-ci

Build Options

OptionUsageReference
Entry pointsentry: ['src/*.ts', '!**/*.test.ts']option-entry
Output formatsformat: ['esm', 'cjs', 'iife', 'umd']option-output-format
Output directoryoutDir: 'dist', outExtensionsoption-output-directory
Type declarationsdts: true, dts: { sourcemap, compilerOptions, vue }option-dts
Target environmenttarget: 'es2020', target: 'esnext'option-target
Platformplatform: 'node', platform: 'browser'option-platform
Tree shakingtreeshake: true, custom optionsoption-tree-shaking
Minificationminify: true, minify: 'dce-only'option-minification
Source mapssourcemap: true, 'inline', 'hidden'option-sourcemap
Watch modewatch: true, watch optionsoption-watch-mode
Cleaningclean: true, clean patternsoption-cleaning
Log levellogLevel: 'silent', failOnWarn: falseoption-log-level

Dependency Handling

FeatureUsageReference
Never bundledeps: { neverBundle: ['react', /^@myorg\//] }option-dependencies
Always bundledeps: { alwaysBundle: ['dep-to-bundle'] }option-dependencies
Only bundledeps: { onlyBundle: ['cac', 'bumpp'] } - Whitelistoption-dependencies
Skip node_modulesdeps: { skipNodeModulesBundle: true }option-dependencies
Auto externalAutomatic peer/dependency externalizationoption-dependencies

Output Enhancement

FeatureUsageReference
Shimsshims: true - Add ESM/CJS compatibilityoption-shims
CJS defaultcjsDefault: true (default) / falseoption-cjs-default
Package exportsexports: true - Auto-generate exports fieldoption-package-exports
CSS handling[experimental] css: { ... } — full pipeline with preprocessors, Lightning CSS, PostCSS, code splitting; requires @tsdown/cssoption-css
CSS injectcss: { inject: true } — preserve CSS imports in JS outputoption-css
Unbundle modeunbundle: true - Preserve directory structureoption-unbundle
Root directoryroot: 'src' - Control output directory mappingoption-root
Executable[experimental] exe: true - Bundle as standalone executable, cross-platform via @tsdown/exeoption-exe
Package validationpublint: true, attw: true - Validate packageoption-lint

Framework & Runtime Support

FrameworkGuideReference
ReactJSX transform, React Compilerrecipe-react
VueSFC support, JSXrecipe-vue
SolidSolidJS JSX transformrecipe-solid
SvelteSvelte component libraries (source distribution recommended)recipe-svelte
WASMWebAssembly modules via rolldown-plugin-wasmrecipe-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' },
    ],
  },
})

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

  1. Always generate type declarations for TypeScript libraries: 
    { dts: true }
  2. Externalize dependencies to avoid bundling unnecessary code: 
    { deps: { neverBundle: [/^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

More skills

A
Antfu

antfu

V
Turborepo

vercel

G
Datanalysis Credit Risk

github