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.
Blazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.
# 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
import { defineConfig } from "tsdown";
export default defineConfig({
entry: ["./src/index.ts"],
format: ["esm", "cjs"],
dts: true,
clean: true,
});
| 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 |
| 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: 'ci-only' | option-log-level |
| Feature | Usage | Reference |
|---|---|---|
| External deps | external: ['react', /^@myorg\//] | option-dependencies |
| Inline deps | noExternal: ['dep-to-bundle'] | option-dependencies |
| Auto external | Automatic peer/dependency externalization | option-dependencies |
| 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] Still in development | option-css |
| Unbundle mode | unbundle: true - Preserve directory structure | option-unbundle |
| Package validation | publint: true, attw: true - Validate package | option-lint |
| Framework | Guide | Reference |
|---|---|---|
| React | JSX transform, Fast Refresh | recipe-react |
| Vue | SFC support, JSX | recipe-vue |
| WASM | WebAssembly modules via rolldown-plugin-wasm | recipe-wasm |
export default defineConfig({
entry: ["src/index.ts"],
format: ["esm", "cjs"],
dts: true,
clean: true,
});
export default defineConfig({
entry: {
index: "src/index.ts",
utils: "src/utils.ts",
cli: "src/cli.ts",
},
format: ["esm", "cjs"],
dts: true,
});
export default defineConfig({
entry: ["src/index.ts"],
format: ["iife"],
globalName: "MyLib",
platform: "browser",
minify: true,
});
export default defineConfig({
entry: ["src/index.tsx"],
format: ["esm", "cjs"],
dts: true,
external: ["react", "react-dom"],
plugins: [
// React Fast Refresh support
],
});
export default defineConfig({
entry: ["src/**/*.ts", "!**/*.test.ts"],
unbundle: true, // Preserve file structure
format: ["esm"],
dts: true,
});
export default defineConfig({
entry: ["src/index.ts"],
format: ["esm", "cjs"],
dts: true,
failOnWarn: "ci-only",
publint: "ci-only",
attw: "ci-only",
});
import { wasm } from "rolldown-plugin-wasm";
import { defineConfig } from "tsdown";
export default defineConfig({
entry: ["src/index.ts"],
plugins: [wasm()],
});
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!");
},
},
});
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",
},
]);
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,
};
});
Use glob patterns to build multiple packages:
export default defineConfig({
workspace: "packages/*",
entry: ["src/index.ts"],
format: ["esm", "cjs"],
dts: true,
});
# 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
Always generate type declarations for TypeScript libraries:
{
dts: true;
}
Externalize dependencies to avoid bundling unnecessary code:
{
external: [/^react/, /^@myorg\//];
}
Use tree shaking for optimal bundle size:
{
treeshake: true;
}
Enable minification for production builds:
{
minify: true;
}
Add shims for better ESM/CJS compatibility:
{
shims: true;
} // Adds __dirname, __filename, etc.
Auto-generate package.json exports:
{
exports: true;
} // Creates proper exports field
Use watch mode during development:
tsdown --watch
Preserve structure for utilities with many files:
{
unbundle: true;
} // Keep directory structure
Validate packages in CI before publishing:
{ publint: 'ci-only', attw: 'ci-only' }