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

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,
  external: ["react", "react-dom"],
  plugins: [
    // React Fast Refresh support
  ],
});

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",
  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()],
});

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 --outDir lib            # Custom output directory
tsdown --minify                # Enable minification
tsdown --dts                   # Generate declarations

# Entry options
tsdown src/index.ts            # Single entry
tsdown src/*.ts                # Glob patterns
tsdown src/a.ts src/b.ts       # Multiple entries

# Development
tsdown --watch                 # Watch mode
tsdown --sourcemap             # Generate source maps
tsdown --clean                 # Clean output directory

Best Practices

1. Always generate type declarations for TypeScript libraries:

``ts { dts: true; } ``

1. Externalize dependencies to avoid bundling unnecessary code:

``ts { external: [/^react/, /^@myorg\//]; } ``

1. Use tree shaking for optimal bundle size:

``ts { treeshake: true; } ``

1. Enable minification for production builds:

``ts { minify: true; } ``

1. Add shims for better ESM/CJS compatibility:

``ts { shims: true; } // Adds dirname, filename, etc. ``

1. Auto-generate package.json exports:

``ts { exports: true; } // Creates proper exports field ``

1. Use watch mode during development:

``bash tsdown --watch ``

1. Preserve structure for utilities with many files:

``ts { unbundle: true; } // Keep directory structure ``

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