Skills
Skill 8 of 19
Bundle TypeScript and JavaScript libraries with blazing-fast speed powered by Rolldown.
3 minutes · 556 words · 29 sections
Install
npx skills add antfu/skills --skill tsdownnpx skills add antfu/skillsThe first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.
Blazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.
tsdown requires Node.js 22.18.0 or higher to run (build-time only). However, the bundled output can target much lower Node.js versions via the target (opens in a new tab) option, so libraries built with tsdown are not locked to Node.js 22+ at runtime.
If your package needs to support Node.js 18 / 20:
target: 'node18' or target: 'node20').# 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-migrateimport { 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 (opens in a new tab) |
| Configuration File | Config file formats, multiple configs, workspace | option-config-file (opens in a new tab) |
| CLI Reference | All CLI commands and options | reference-cli (opens in a new tab) |
| Migrate from tsup | Migration guide and compatibility notes | guide-migrate-from-tsup (opens in a new tab) |
| Plugins | Rolldown, Rollup, Unplugin support | advanced-plugins (opens in a new tab) |
For comprehensive migration assistance with complete option mappings, install the dedicated
tsdown-migrate(opens in a new tab) skill:npx skills add rolldown/tsdown --skill tsdown-migrate| Hooks | Lifecycle hooks for custom logic | advanced-hooks (opens in a new tab) | | Programmatic API | Build from Node.js scripts | advanced-programmatic (opens in a new tab) | | Rolldown Options | Pass options directly to Rolldown | advanced-rolldown-options (opens in a new tab) | | CI Environment | CI detection,'ci-only'/'local-only'values | advanced-ci (opens in a new tab) |
| Option | Usage | Reference |
|---|---|---|
| Entry points | entry: ['src/*.ts', '!**/*.test.ts'] | option-entry (opens in a new tab) |
| Output formats | format: ['esm', 'cjs', 'iife', 'umd'] | option-output-format (opens in a new tab) |
| Output directory | outDir: 'dist', outExtensions | option-output-directory (opens in a new tab) |
| Type declarations | dts: true, dts: { sourcemap, compilerOptions, vue } | option-dts (opens in a new tab) |
| Target environment | target: 'es2020', target: 'esnext' | option-target (opens in a new tab) |
| Platform | platform: 'node', platform: 'browser' | option-platform (opens in a new tab) |
| Tree shaking | treeshake: true, custom options | option-tree-shaking (opens in a new tab) |
| Minification | minify: true, minify: 'dce-only' | option-minification (opens in a new tab) |
| Source maps | sourcemap: true, 'inline', 'hidden' | option-sourcemap (opens in a new tab) |
| Watch mode | watch: true, watch options | option-watch-mode (opens in a new tab) |
| Cleaning | clean: true, clean patterns | option-cleaning (opens in a new tab) |
| Log level | logLevel: 'silent', failOnWarn: false | option-log-level (opens in a new tab) |
| Feature | Usage | Reference |
|---|---|---|
| Never bundle | deps: { neverBundle: ['react', /^@myorg\//] } | option-dependencies (opens in a new tab) |
| Always bundle | deps: { alwaysBundle: ['dep-to-bundle'] } | option-dependencies (opens in a new tab) |
| Only bundle | deps: { onlyBundle: ['cac', 'bumpp'] } - Whitelist | option-dependencies (opens in a new tab) |
| Skip node_modules | deps: { skipNodeModulesBundle: true } | option-dependencies (opens in a new tab) |
| Auto external | Automatic dependency/peer/optional externalization | option-dependencies (opens in a new tab) |
| Feature | Usage | Reference |
|---|---|---|
| Shims | shims: true - Add ESM/CJS compatibility | option-shims (opens in a new tab) |
| CJS default | cjsDefault: true (default) / false | option-cjs-default (opens in a new tab) |
| Package exports | exports: true - Generate exports field | option-package-exports (opens in a new tab) |
| CSS handling | [experimental] css: { ... } — full pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, code splitting; requires @tsdown/css | option-css (opens in a new tab) |
| CSS modules | css: { modules: { localsConvention: 'camelCase' } } — scoped class names for .module.css files | option-css (opens in a new tab) |
| CSS inject | css: { inject: true } — preserve CSS imports in JS output | option-css (opens in a new tab) |
| Unbundle mode | unbundle: true - Preserve directory structure | option-unbundle (opens in a new tab) |
| Root directory | root: 'src' - Control output directory mapping | option-root (opens in a new tab) |
| Executable | [experimental] exe: true - Bundle as standalone executable, cross-platform via @tsdown/exe | option-exe (opens in a new tab) |
| Package validation | publint: true, attw: true - Validate package | option-lint (opens in a new tab) |
| Framework | Guide | Reference |
|---|---|---|
| React | JSX transform, React Compiler | recipe-react (opens in a new tab) |
| Vue | SFC support, JSX | recipe-vue (opens in a new tab) |
| Solid | SolidJS JSX transform | recipe-solid (opens in a new tab) |
| Svelte | Svelte component libraries (source distribution recommended) | recipe-svelte (opens in a new tab) |
| WASM | WebAssembly modules via rolldown-plugin-wasm | recipe-wasm (opens in a new tab) |
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,
deps: {
neverBundle: ['react', 'react-dom'],
},
inputOptions: {
jsx: { runtime: 'automatic' },
},
})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', // opt-in: fail on warnings in CI
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,
target: 'chrome100',
css: {
preprocessorOptions: {
scss: {
additionalData: `@use "src/styles/variables" as *;`,
},
},
},
})export default defineConfig({
entry: ['src/cli.ts'],
exe: true,
})@tsdown/exe)export default defineConfig({
entry: ['src/cli.ts'],
exe: {
targets: [
{ platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },
{ platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },
{ platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },
],
},
})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 -d lib # Custom output directory (--out-dir)
tsdown --minify # Enable minification
tsdown --dts # Generate declarations
tsdown --exe # Bundle as standalone executable
tsdown --unbundle # Bundleless mode
# Entry options
tsdown src/index.ts # Single entry
tsdown src/*.ts # Glob patterns
tsdown src/a.ts src/b.ts # Multiple entries
# Workspace / Monorepo
tsdown -W # Enable workspace mode
tsdown -W -F my-package # Filter specific package
tsdown --filter /^pkg-/ # Filter by regex
# Development
tsdown --watch # Watch mode
tsdown --sourcemap # Generate source maps
tsdown --clean # Clean output directory
tsdown --from-vite # Reuse Vite config
tsdown --tsconfig tsconfig.build.json # Custom tsconfigAlways generate type declarations for TypeScript libraries:
{ dts: true }Externalize dependencies to avoid bundling unnecessary code:
{ deps: { neverBundle: [/^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 fieldUse watch mode during development:
tsdown --watchPreserve structure for utilities with many files:
{ unbundle: true } // Keep directory structureValidate packages in CI before publishing:
{ publint: 'ci-only', attw: 'ci-only' }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.
The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.
main, last pushed 23 June 2026.SKILL.md, not by matching a directory convention. One layout observed: skills/*/SKILL.md.h1 and no skipped levels:/antfu/skills.md, and each skill at its own .md URL.41 files · 162 KB
Everything this skill ships beside its prose. All of it is set here, as subchapters of skill 8.
Documentation the agent loads on demand, rather than up front.
Everything else published alongside the skill.