tsdown Setup Guide

What tsdown Is

tsdown is a Rolldown-based TypeScript library build tool. It fills the same role as tsup (build TypeScript packages into distributable bundles), but uses Rolldown for bundling and OXC for transforms instead of esbuild. It shares the same ecosystem as Vite and is maintained by the Rolldown team.

Install

npm install -D tsdown

Basic Config

Create tsdown.config.ts in your project root:

import { defineConfig } from "tsdown";

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

Add scripts to package.json:

{
  "scripts": {
    "build": "tsdown",
    "dev": "tsdown --watch"
  }
}

Key Features

Rolldown bundler - tree shaking, code splitting, and bundling powered by the same engine as Vite’s production builds
OXC transforms - TypeScript and JSX stripping via OXC instead of esbuild, matching the transform pipeline in Vite 7+
Isolated declarations - generate .d.ts files using OXC’s oxc_isolated_declarations crate (no full tsc needed for declaration-only output)
Multiple formats - output ESM, CJS, or both from a single config
Shared async runtime - uses the same tokio runtime exported by Rolldown (createTokioRuntime), so Rolldown and tsdown share a single async runtime when used together

Config Options

import { defineConfig } from "tsdown";

export default defineConfig({
  // Entry points (glob patterns supported)
  entry: ["src/index.ts", "src/cli.ts"],

  // Output formats
  format: ["esm", "cjs"],

  // Generate .d.ts declaration files
  dts: true,

  // Output directory
  outDir: "dist",

  // Clean output directory before build
  clean: true,

  // External packages (not bundled)
  external: ["react", "react-dom"],

  // Target environment
  target: "node18",

  // Sourcemaps
  sourcemap: true,
});

Comparison with tsup

Feature	tsup	tsdown
Bundler	esbuild	Rolldown
Transforms	esbuild	OXC
Tree shaking	esbuild (basic)	Rolldown (more thorough)
Declaration files	tsc or rollup-plugin-dts	OXC isolated declarations
Config format	Compatible	Largely compatible
CLI interface	`tsup src/index.ts`	`tsdown src/index.ts`

The config format is largely compatible with tsup. For most projects, renaming tsup.config.ts to tsdown.config.ts and swapping the import works.

Migration from tsup

Replace the dependency: npm uninstall tsup && npm install -D tsdown
Rename tsup.config.ts to tsdown.config.ts
Update the import: import { defineConfig } from "tsdown"
Update scripts in package.json: replace tsup with tsdown
Run npm run build and compare output

Most tsup configs work without changes. Check for tsup-specific options that may not have equivalents yet.

Note on Stability

tsdown is actively developed alongside Rolldown. Track the rolldown/tsdown repository for updates. Pin your version and review the changelog when upgrading, as the API may change between releases.

Next Steps

Rolldown Architecture - how the bundler works
Vite Architecture - the shared Rolldown + OXC pipeline
Oxc Architecture - the transform engine