/tsdown

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

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

Debugging

# Verbose output
DEBUG=tsdown:* tsdown

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