tsdown
Overview
tsdown is an elegant library bundler built on Rolldown (Rust-based), providing a complete out-of-the-box solution for building TypeScript and JavaScript libraries. It handles source transformation, multiple output formats (ESM, CJS, IIFE, UMD), TypeScript declaration file generation, and package.json exports field generation with sensible defaults.
When to use: Building TypeScript libraries for npm, generating declaration files, producing dual ESM/CJS packages, bundling CLI tools, library development with watch mode, migrating from tsup.
When NOT to use: Application bundling (use Vite/Rolldown directly), server-side rendering frameworks (use framework bundlers), projects that need Webpack-specific features, simple scripts that need no bundling.
Quick Reference
| Pattern |
API |
Key Points |
| Basic build |
npx tsdown |
Auto-detects src/index.ts entry |
| Config file |
tsdown.config.ts |
defineConfig() for type safety |
| Entry points |
entry: ['src/index.ts'] |
String, array, or object for named entries |
| Output formats |
format: ['esm', 'cjs'] |
ESM, CJS, IIFE, UMD supported |
| Declaration files |
dts: true |
Auto-detects from package.json types field |
| Fixed extensions |
fixedExtension: true |
Forces .mjs/.cjs and .d.mts/.d.cts |
| Externals |
external: ['react'] |
node_modules external by default |
| Bundle deps |
noExternal: ['lodash-es'] |
Force-bundle specific dependencies |
| Target |
target: 'node18' |
ES version or Node version |
| Platform |
platform: 'node' |
node, browser, or neutral |
| Minification |
minify: true |
Tree shaking enabled separately |
| Tree shaking |
treeshake: true |
Dead code elimination |
| Source maps |
sourcemap: true |
Inline or external source maps |
| Watch mode |
tsdown --watch |
Auto-rebuild on file changes |
| Clean output |
clean: true |
Remove output directory before build |
| Validation |
--publint --attw |
Package quality checks post-build |
| Size report |
--report |
Bundle size with gzip/brotli stats |
| Multiple configs |
defineConfig([...]) |
Array of configs for different outputs |
| Dynamic config |
defineConfig((opts) => {}) |
Function receiving CLI options |
| Programmatic API |
import { build } |
Use in Node.js scripts |
| Banner/Footer |
banner: { js: '...' } |
Prepend/append to output files |
| onSuccess hook |
onSuccess: async () => {} |
Run after successful build |
| Node protocol |
nodeProtocol: true |
Add/strip node: prefix on built-in imports |
Common Mistakes
| Mistake |
Correct Pattern |
Not setting fixedExtension with dual formats |
Use fixedExtension: true for .mjs/.cjs when publishing both ESM and CJS |
| Bundling all node_modules into library output |
Dependencies are external by default; use noExternal only for specific deps |
Using dts: true without TypeScript configured |
Ensure tsconfig.json exists with proper compilerOptions |
Setting target too low for modern syntax |
Match target to your minimum supported Node/browser version |
Missing types field in package.json |
Add types or exports types condition for declaration resolution |
| Not cleaning output before format changes |
Use clean: true to avoid stale files from previous builds |
Inline external for Node built-ins |
Node built-ins (node:fs, etc.) are auto-externalized on platform: 'node' |
| Using interactive CLI flags in CI |
Use config file or non-interactive CLI flags for CI builds |
Delegation
- Build configuration review: Use
Task agent to analyze tsdown config for correctness
- Package publishing: Use
Explore agent to verify package.json exports and types fields
- Migration from tsup: Use
Task agent to map tsup options to tsdown equivalents
References
- Configuration: config file, entry points, output formats, target, platform, externals
- Declaration files: DTS generation, isolated declarations, type bundling
- Advanced features: plugins, code splitting, tree shaking, watch mode, validation
1---2name: tsdown3description: tsdown TypeScript bundler built on Rolldown for libraries and packages. Use when bundling TypeScript libraries, generating declaration files, or publishing npm packages. Use for tsdown, bundler, rolldown, dts, declaration, library-build, esm, cjs, treeshake.4license: MIT5---6
7# tsdown
8
9## Overview
10
11tsdown is an elegant library bundler built on Rolldown (Rust-based), providing a complete out-of-the-box solution for building TypeScript and JavaScript libraries. It handles source transformation, multiple output formats (ESM, CJS, IIFE, UMD), TypeScript declaration file generation, and package.json exports field generation with sensible defaults.
12
13**When to use:** Building TypeScript libraries for npm, generating declaration files, producing dual ESM/CJS packages, bundling CLI tools, library development with watch mode, migrating from tsup.
14
15**When NOT to use:** Application bundling (use Vite/Rolldown directly), server-side rendering frameworks (use framework bundlers), projects that need Webpack-specific features, simple scripts that need no bundling.
16
17## Quick Reference
18
19| Pattern | API | Key Points |
20| ----------------- | ---------------------------- | -------------------------------------------- |
21| Basic build | `npx tsdown` | Auto-detects `src/index.ts` entry |
22| Config file | `tsdown.config.ts` | `defineConfig()` for type safety |
23| Entry points | `entry: ['src/index.ts']` | String, array, or object for named entries |
24| Output formats | `format: ['esm', 'cjs']` | ESM, CJS, IIFE, UMD supported |
25| Declaration files | `dts: true` | Auto-detects from package.json `types` field |
26| Fixed extensions | `fixedExtension: true` | Forces `.mjs`/`.cjs` and `.d.mts`/`.d.cts` |
27| Externals | `external: ['react']` | node_modules external by default |
28| Bundle deps | `noExternal: ['lodash-es']` | Force-bundle specific dependencies |
29| Target | `target: 'node18'` | ES version or Node version |
30| Platform | `platform: 'node'` | `node`, `browser`, or `neutral` |
31| Minification | `minify: true` | Tree shaking enabled separately |
32| Tree shaking | `treeshake: true` | Dead code elimination |
33| Source maps | `sourcemap: true` | Inline or external source maps |
34| Watch mode | `tsdown --watch` | Auto-rebuild on file changes |
35| Clean output | `clean: true` | Remove output directory before build |
36| Validation | `--publint --attw` | Package quality checks post-build |
37| Size report | `--report` | Bundle size with gzip/brotli stats |
38| Multiple configs | `defineConfig([...])` | Array of configs for different outputs |
39| Dynamic config | `defineConfig((opts) => {})` | Function receiving CLI options |
40| Programmatic API | `import { build }` | Use in Node.js scripts |
41| Banner/Footer | `banner: { js: '...' }` | Prepend/append to output files |
42| onSuccess hook | `onSuccess: async () => {}` | Run after successful build |
43| Node protocol | `nodeProtocol: true` | Add/strip `node:` prefix on built-in imports |
44
45## Common Mistakes
46
47| Mistake | Correct Pattern |
48| ----------------------------------------------- | ----------------------------------------------------------------------------- |
49| Not setting `fixedExtension` with dual formats | Use `fixedExtension: true` for `.mjs`/`.cjs` when publishing both ESM and CJS |
50| Bundling all node_modules into library output | Dependencies are external by default; use `noExternal` only for specific deps |
51| Using `dts: true` without TypeScript configured | Ensure `tsconfig.json` exists with proper `compilerOptions` |
52| Setting `target` too low for modern syntax | Match target to your minimum supported Node/browser version |
53| Missing `types` field in package.json | Add `types` or `exports` types condition for declaration resolution |
54| Not cleaning output before format changes | Use `clean: true` to avoid stale files from previous builds |
55| Inline `external` for Node built-ins | Node built-ins (`node:fs`, etc.) are auto-externalized on `platform: 'node'` |
56| Using interactive CLI flags in CI | Use config file or non-interactive CLI flags for CI builds |
57
58## Delegation
59
60- **Build configuration review**: Use `Task` agent to analyze tsdown config for correctness
61- **Package publishing**: Use `Explore` agent to verify package.json exports and types fields
62- **Migration from tsup**: Use `Task` agent to map tsup options to tsdown equivalents
63
64## References
65
66- [Configuration: config file, entry points, output formats, target, platform, externals](references/configuration.md)
67- [Declaration files: DTS generation, isolated declarations, type bundling](references/declaration-files.md)
68- [Advanced features: plugins, code splitting, tree shaking, watch mode, validation](references/advanced-features.md)
oakoss