Tsdown

tsdown

Rolldown + Oxc powered TypeScript bundler. Drop-in tsup replacement.

When to Use

• Building TypeScript libraries
• Generating .d.ts declarations
• Publishing npm packages
• Dual ESM/CJS output
• Vue/React component libraries

Quick Start

npm i -D tsdown typescript

// tsdown.config.ts
import { defineConfig } from 'tsdown'

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

tsdown           # Build
tsdown --watch   # Watch mode

Reference Files

Loading Files

Consider loading these reference files based on your task:

• [ ] references/config.md - if setting up tsdown.config.ts, CLI, or entry points
• [ ] references/output.md - if configuring output format, target, .d.ts, exports, or validation
• [ ] references/features.md - if using shims, unbundle, watch mode, framework integrations, or WebAssembly
• [ ] references/advanced.md - if writing plugins, using linting/validation, programmatic API, or migrating from tsup

DO NOT load all files at once. Load only what's relevant to your current task.

Cross-Skill References

• Library patterns → Use ts-library skill
• Vue component libs → Use vue skill
• Package management → Use pnpm skill

Advanced

Plugins

Supported Types

• Rolldown - Native support
• Unplugin - Most unplugin-* work
• Rollup - Most work (may need type cast)
• Vite - May work if not using Vite internals

import UnpluginVue from 'unplugin-vue/rolldown'
import SomeRollupPlugin from 'some-rollup-plugin'

defineConfig({
  plugins: [
    UnpluginVue({ isProduction: true }),
    SomeRollupPlugin() as any,  // Type cast for Rollup plugins
  ],
})

Custom Plugin

defineConfig({
  plugins: [
    {
      name: 'my-plugin',
      transform(code, id) {
        if (id.endsWith('.txt')) {
          return `export default ${JSON.stringify(code)}`
        }
      },
    },
  ],
})

See Rolldown Plugin API.

Hooks

Build lifecycle:

// Object syntax
defineConfig({
  hooks: {
    'build:prepare': (context) => {
      console.log('Preparing build...')
    },
    'build:before': (context, format) => {
      console.log(`Building ${format}...`)
    },
    'build:done': async (context) => {
      await generateDocs()
      console.log('Build complete!')
    },
  },
})

// Function syntax
defineConfig({
  hooks(hooks) {
    hooks.hook('build:prepare', () => {
      console.log('Starting...')
    })
  },
})

Programmatic API

import { build } from 'tsdown'

await build({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  outDir: 'dist',
  dts: true,
  exports: true,
})

Multiple builds:

await build([
  { entry: ['src/node.ts'], platform: 'node', outDir: 'dist/node' },
  { entry: ['src/browser.ts'], platform: 'browser', outDir: 'dist/browser' },
])

Rolldown Options

inputOptions

defineConfig({
  inputOptions: {
    cwd: './custom-directory',
    resolve: {
      mainFields: ['module', 'main'],
      alias: { '@': './src' },
    },
    transform: {
      jsx: 'react',
    },
  },
})

Function syntax for format-specific:

defineConfig({
  inputOptions(options, format) {
    if (format === 'cjs') {
      options.cwd = './cjs-specific'
    }
    return options
  },
})

outputOptions

defineConfig({
  outputOptions: {
    legalComments: 'inline',  // Preserve license headers
  },
})

Format-specific:

defineConfig({
  outputOptions(options, format) {
    if (format === 'esm') {
      options.legalComments = 'inline'
    }
    return options
  },
})

Migration from tsup

Automatic

npx tsdown-migrate
npx tsdown-migrate packages/*  # Monorepo
npx tsdown-migrate --dry-run   # Preview

Changed Defaults

Breaking Changes (v0.19+)

• Removed: dts.resolve option (v0.20+)
• Removed: silent option - use log levels instead
• Renamed: debugLogs → debug
• Renamed: debug.devtools → devtools.ui
• Exports: exports.legacy controls main/module field generation
• Exports: exports.exclude now excludes extension names

No Stub Mode

tsdown doesn't support stub mode. Alternatives:

1. Watch mode: tsdown --watch 2. Dev exports: exports: { devExports: true } 3. TypeScript runners: vite-node, tsx, jiti, Node.js v22.18+

Performance Tips

1. Enable isolatedDeclarations in tsconfig for fast .d.ts 2. Use skipNodeModulesBundle: true if not bundling deps 3. Disable sourcemaps in production if not needed

Package Validation

publint

Validates package.json exports configuration:

defineConfig({
  publint: true,  // Enable
  publint: 'warning',  // Set severity: 'warning' | 'error' | 'suggestion'
  publint: 'ci-only',  // Run only in CI
})

tsdown --publint

attw (Are The Types Wrong?)

Validates TypeScript declarations across module resolutions:

defineConfig({
  attw: {
    profile: 'strict',  // 'strict' | 'node16' | 'esm-only'
    level: 'error',     // 'warn' | 'error'
    ignoreRules: ['false-cjs', 'named-exports'],
  },
  attw: 'ci-only',  // Run only in CI
})

tsdown --attw

Debugging

# Verbose output
DEBUG=tsdown:* tsdown

# Dry run (migration)
npx tsdown-migrate --dry-run

Devtools

Rolldown devtools for debugging:

defineConfig({
  devtools: {
    ui: true,  // Enable UI (renamed from debug.devtools)
  },
})

Configuration & CLI

Config File

Supported files (searched in order):

• tsdown.config.ts / .mts / .cts
• tsdown.config.js / .mjs / .cjs
• tsdown.config.json
• tsdown field in package.json

// tsdown.config.ts
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: 'src/index.ts',
  dts: true,
  exports: true,
})

Multiple Configurations

import { defineConfig } from 'tsdown'

export default defineConfig([
  {
    entry: 'src/node.ts',
    platform: 'node',
  },
  {
    entry: 'src/browser.ts',
    platform: 'browser',
  },
])

Entry Points

// Single entry
defineConfig({
  entry: 'src/index.ts',
})

// Multiple entries
defineConfig({
  entry: ['src/entry1.ts', 'src/entry2.ts'],
})

// Entry aliases → dist/main.js, dist/utils.js
defineConfig({
  entry: {
    main: 'src/index.ts',
    utils: 'src/utils.ts',
  },
})

// Glob patterns
defineConfig({
  entry: 'src/**/*.ts',
})

// Mixed array and object entries
defineConfig({
  entry: [
    'src/index.ts',
    { cli: 'src/cli.ts' },
  ],
})

CLI Commands

tsdown                          # Build
tsdown src/index.ts             # Specify entry
tsdown --watch                  # Watch mode
tsdown -w

tsdown --config ./path/to/config
tsdown --no-config              # Skip config file

CLI Options

# Output
--format esm|cjs|iife|umd
--format esm --format cjs       # Multiple formats
-d ./build                      # Output dir
--out-dir ./build

# Declaration files
--dts

# Target
--target es2020
--target node20
--no-target                     # Preserve modern syntax

# Platform
--platform node|browser|neutral

# Optimization
--minify
--sourcemap
--treeshake
--no-treeshake

# Cleaning
--clean                         # Default: true
--no-clean

# External
--external lodash
--external "@my-scope/*"

# Watch
--watch [path]
--ignore-watch node_modules

# Env
--env.NODE_ENV=production
--env-file .env.production
--env-prefix APP_

# Post-build
--on-success "echo Done!"

# Copy assets
--copy public

# Package exports
--exports

# Validation
--publint
--attw

CLI Flag Patterns

--foo              # foo: true
--no-foo           # foo: false
--foo.bar          # foo: { bar: true }
--format esm --format cjs  # format: ['esm', 'cjs']

Config Loaders

tsdown --config-loader auto     # Default
tsdown --config-loader native   # Node.js TypeScript
tsdown --config-loader unrun    # More powerful

Extend Vite/Vitest Config

Reuse resolve and plugins:

tsdown --from-vite              # Load vite.config.*
tsdown --from-vite vitest       # Load vitest.config.*

Common Configurations

Pure ESM Library

defineConfig({
  entry: 'src/index.ts',
  format: 'esm',
  dts: true,
  exports: true,
  target: 'es2020',
})

Dual ESM/CJS

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

Node.js CLI

defineConfig({
  entry: 'src/cli.ts',
  format: 'esm',
  platform: 'node',
  dts: true,
  shims: true,  // __dirname, __filename in ESM
})

Browser Library

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

Features

Tree Shaking

Enabled by default - removes unused code.

defineConfig({
  treeshake: true,   // Default
  treeshake: false,  // Disable
})

Minification

defineConfig({
  minify: true,
})

Uses Oxc (fast, currently alpha).

Source Maps

defineConfig({
  sourcemap: true,
})

Auto-enabled if declarationMap: true in tsconfig.json.

Shims

CJS in ESM

__dirname and __filename not available in ESM:

defineConfig({
  shims: true,  // Provides __dirname, __filename
})

require in ESM

Auto-injected when platform: 'node':

// Generated:
const require = createRequire(import.meta.url)

ESM in CJS

Always enabled - import.meta.url, import.meta.dirname, import.meta.filename work in CJS.

CJS Default Export

When CJS output has only default export:

// Source
export default function greet() {}

// CJS Output
module.exports = greet

// Declaration
declare function greet(): void
export = greet

Unbundle Mode

Transpile-only - preserves file structure:

defineConfig({
  entry: ['src/index.ts'],
  unbundle: true,
})

Input:

src/
  index.ts
  mod.ts

Output:

dist/
  index.js
  mod.js

Watch Mode

defineConfig({
  watch: true,
  // Or specific paths
  watch: ['./src', './lib'],
})

tsdown --watch
tsdown --watch ./src
tsdown --ignore-watch node_modules

Post-Build Command

tsdown --watch --on-success "node dist/index.mjs"

Copy Assets

tsdown --copy public

Environment Variables

tsdown --env.NODE_ENV=production
tsdown --env-file .env.production
tsdown --env-prefix APP_

Node Protocol

Control Node.js built-in imports:

defineConfig({
  nodeProtocol: true,     // fs → node:fs
  nodeProtocol: 'strip',  // node:fs → fs
  nodeProtocol: false,    // Keep as-is (default)
})

CSS

defineConfig({
  css: {
    splitting: false,      // Single CSS file
    fileName: 'styles.css',
  },
})

CSS targeting (requires unplugin-lightningcss):

pnpm add -D unplugin-lightningcss

JSX

Built-in support via Rolldown:

defineConfig({
  inputOptions: {
    transform: {
      jsx: 'react',  // Classic transform
    },
  },
})

Framework Support

React

// tsdown.config.ts
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['./src/index.ts'],
  platform: 'neutral',
  dts: true,
})

React Compiler:

pnpm add -D @rollup/plugin-babel babel-plugin-react-compiler

import pluginBabel from '@rollup/plugin-babel'

defineConfig({
  plugins: [
    pluginBabel({
      babelHelpers: 'bundled',
      parserOpts: {
        sourceType: 'module',
        plugins: ['jsx', 'typescript'],
      },
      plugins: ['babel-plugin-react-compiler'],
      extensions: ['.js', '.jsx', '.ts', '.tsx'],
    }),
  ],
})

Vue

pnpm add -D unplugin-vue vue-tsc

import { defineConfig } from 'tsdown'
import Vue from 'unplugin-vue/rolldown'

export default defineConfig({
  entry: ['./src/index.ts'],
  platform: 'neutral',
  plugins: [Vue({ isProduction: true })],
  dts: { vue: true },
})

WebAssembly

pnpm add -D rolldown-plugin-wasm

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

export default defineConfig({
  plugins: [
    wasm({
      maxFileSize: 14000,  // Inline if < 14KB
      targetEnv: 'auto',   // 'auto' | 'node' | 'browser'
    }),
  ],
})

Import methods:

import { add } from './add.wasm'              // Direct
import init from './module.wasm?init'         // Async
import initSync from './module.wasm?init&sync' // Sync

Supports wasm-bindgen for bundler and web targets.

Quick Start Templates

npx create-tsdown@latest -t vue
npx create-tsdown@latest -t react
npx create-tsdown@latest -t react-compiler

Output Options

Format

Default: esm

defineConfig({
  format: 'esm',                 // ECMAScript Modules
  format: 'cjs',                 // CommonJS
  format: 'iife',                // Browser script
  format: 'umd',                 // Universal
  format: ['esm', 'cjs'],        // Multiple
})

Format-specific config:

defineConfig({
  format: {
    esm: { target: ['es2015'] },
    cjs: { target: ['node20'] },
  },
})

Output Directory

defineConfig({
  outDir: 'dist',  // Default
})

tsdown -d ./build
tsdown --out-dir ./build

Target

Syntax downleveling (no polyfills):

defineConfig({
  target: 'es2020',
  target: 'node20',
  target: ['chrome100', 'firefox90'],
})

Default: reads from engines.node in package.json.

Disable transformations:

defineConfig({
  target: false,  // Preserve modern syntax
})

Platform

defineConfig({
  platform: 'node',     // Default, Node.js built-ins external
  platform: 'browser',  // Web browsers
  platform: 'neutral',  // Platform-agnostic
})

Module resolution:

• node: mainFields: ['main', 'module']
• browser: mainFields: ['browser', 'module', 'main']
• neutral: relies on exports field only

Declaration Files (.d.ts)

defineConfig({
  dts: true,  // Enable
})

Auto-enabled if types or typings in package.json.

Performance with isolatedDeclarations

For fastest .d.ts generation:

// tsconfig.json
{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}

Uses oxc-transform instead of slower TypeScript.

Declaration Maps

defineConfig({
  dts: {
    sourcemap: true,  // .d.ts.map files
  },
})

Or via tsconfig.json:

{
  "compilerOptions": {
    "declarationMap": true
  }
}

Vue Support

defineConfig({
  dts: { vue: true },  // Requires vue-tsc
})

Dependencies

Default Behavior

Skip All node_modules

defineConfig({
  skipNodeModulesBundle: true,
})

Inline-Only Mode

Warn if dependencies are bundled (useful for libraries):

defineConfig({
  inlineOnly: true,  // Shows warnings for bundled deps
})

Custom External

defineConfig({
  external: ['lodash', /^@my-scope\//],
})

Force Bundle

defineConfig({
  noExternal: ['some-package'],  // Bundle despite being in deps
})

Package Exports

Auto-generate exports, main, module, types:

defineConfig({
  exports: true,
})

Export All Files

defineConfig({
  exports: {
    all: true,  // Not just entry files
  },
})

Legacy Support

Control main and module field generation:

defineConfig({
  exports: {
    legacy: true,  // Default, generates main/module fields
    legacy: false, // Pure ESM, omits main/module if only ESM format
  },
})

Auto-fills types field only when legacy: true.

Dev Exports

Point to source during development:

defineConfig({
  exports: {
    devExports: true,
  },
})

exports → source, publishConfig.exports → built.

CSS Exports

defineConfig({
  css: {
    splitting: false,
    fileName: 'my-library.css',
  },
  exports: true,
})

Custom Exports

defineConfig({
  exports: {
    customExports(pkg, context) {
      pkg['./foo'] = './foo.js'
      return pkg
    },
  },
})

Cleaning

Output directory cleaned by default:

defineConfig({
  clean: true,   // Default
  clean: false,  // Keep existing
})

Example package.json

{
  "name": "my-lib",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "files": ["dist"]
}