Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

tsdown - The Elegant Library Bundler · antfu | DecimalAI

Tsdown

SkillScore100Maintained

tsdown

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.

codingby antfu

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Coding pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/tsdown/SKILL.md

decimalai skills pull tsdown --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/tsdown/SKILL.md https://app.decimal.ai/s/tsdown/SKILL.md

Raw file: /s/tsdown/SKILL.md ↗ · machine-readable summary at /s/tsdown.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

23 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 51d ago

Yes — +65% lift · at higher cost+137% tokens0% turns100% of whole cases pass with skill (23/23)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-01	✗→✓	▲ Improved	400%	0%
case-02	✗→✓	▲ Improved	69%	0%
case-03	✗→✓	▲ Improved	88%	0%
case-04	✗→✓	▲ Improved	189%	0%
case-05	✗→✓	▲ Improved	244%	0%

Showing 5 of 23 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/1/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

antfu / skills

skills/tsdown/SKILL.md

View on GitHub ↗

License MITImported 8/1/2026Version v2Bundled 38 files

Skill contents

references/

SKILL.md

tsdown - The Elegant Library Bundler

Blazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.

Runtime Requirement

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 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:

Build with Node.js 22+ in CI (e.g. set target: 'node18' or target: 'node20').
Test the built output (or the packed tarball) on the lower Node.js versions you intend to support — e.g. using a matrix job that runs the published package's tests on Node.js 18 / 20 / 22.

When to Use

Building TypeScript/JavaScript libraries for npm
Generating TypeScript declaration files (.d.ts)
Bundling for multiple formats (ESM, CJS, IIFE, UMD)
Optimizing bundles with tree shaking and minification
Migrating from tsup with minimal changes
Building React, Vue, Solid, or Svelte component libraries

Quick Start

bash
# 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

Basic Configuration

ts
import { defineConfig } from 'tsdown'

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

Core References

| 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 |

Build Options

| 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: false | option-log-level |

Dependency Handling

| Feature | Usage | Reference | |---------|-------|-----------| | Never bundle | deps: { neverBundle: ['react', /^@myorg\//] } | option-dependencies | | Always bundle | deps: { alwaysBundle: ['dep-to-bundle'] } | option-dependencies | | Only bundle | deps: { onlyBundle: ['cac', 'bumpp'] } - Whitelist | option-dependencies | | Skip node_modules | deps: { skipNodeModulesBundle: true } | option-dependencies | | Auto external | Automatic dependency/peer/optional externalization | option-dependencies |

Output Enhancement

| 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 - Generate exports field | option-package-exports | | CSS handling | experimental] css: { ... } — full pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, code splitting; requires @tsdown/css | option-css | | CSS modules | css: { modules: { localsConvention: 'camelCase' } } — scoped class names for .module.css files | option-css | | CSS inject | css: { inject: true } — preserve CSS imports in JS output | option-css | | Unbundle mode | unbundle: true - Preserve directory structure | option-unbundle | | Root directory | root: 'src' - Control output directory mapping | option-root | | Executable | experimental] exe: true - Bundle as standalone executable, cross-platform via @tsdown/exe | option-exe | | Package validation | publint: true, attw: true - Validate package | option-lint |

Framework & Runtime Support

| Framework | Guide | Reference | |-----------|-------|-----------| | React | JSX transform, React Compiler | recipe-react | | Vue | SFC support, JSX | recipe-vue | | Solid | SolidJS JSX transform | recipe-solid | | Svelte | Svelte component libraries (source distribution recommended) | recipe-svelte | | WASM | WebAssembly modules via rolldown-plugin-wasm | recipe-wasm |

Common Patterns

Basic Library Bundle

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

Multiple Entry Points

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

Browser Library (IIFE/UMD)

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

React Component Library

ts
export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  dts: true,
  deps: {
    neverBundle: ['react', 'react-dom'],
  },
  inputOptions: {
    jsx: { runtime: 'automatic' },
  },
})

Preserve Directory Structure

ts
export default defineConfig({
  entry: ['src/**/*.ts', '!**/*.test.ts'],
  unbundle: true, // Preserve file structure
  format: ['esm'],
  dts: true,
})

CI-Aware Configuration

ts
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',
})

WASM Support

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

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [wasm()],
})

Library with CSS and Sass

ts
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  target: 'chrome100',
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "src/styles/variables" as *;`,
      },
    },
  },
})

Standalone Executable

ts
export default defineConfig({
  entry: ['src/cli.ts'],
  exe: true,
})

Cross-Platform Executable (requires `@tsdown/exe`)

ts
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' },
    ],
  },
})

Advanced with Hooks

ts
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!')
    },
  },
})

Configuration Features

Multiple Configs

Export an array for multiple build configurations:

ts
export default defineConfig([
  {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    dts: true,
  },
  {
    entry: ['src/cli.ts'],
    format: ['esm'],
    platform: 'node',
  },
])

Conditional Config

Use functions for dynamic configuration:

ts
export default defineConfig((options) => {
  const isDev = options.watch
  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
  }
})

Workspace/Monorepo

Use glob patterns to build multiple packages:

ts
export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
})

CLI Quick Reference

bash
# 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 tsconfig

Best Practices

Always generate type declarations for TypeScript libraries:

ts { dts: true }

Externalize dependencies to avoid bundling unnecessary code:

ts { deps: { neverBundle: [/^react/, /^@myorg\//] } }

Use tree shaking for optimal bundle size:

ts { treeshake: true }

Enable minification for production builds:

ts { minify: true }

Add shims for better ESM/CJS compatibility:

ts { shims: true } // Adds __dirname, __filename, etc.

Auto-generate package.json exports:

ts { exports: true } // Creates proper exports field

Use watch mode during development:

bash tsdown --watch

Preserve structure for utilities with many files:

ts { unbundle: true } // Keep directory structure

Validate packages in CI before publishing:

ts { publint: 'ci-only', attw: 'ci-only' }

Resources

Documentation: https://tsdown.dev
GitHub: https://github.com/rolldown/tsdown
Rolldown: https://rolldown.rs
Migration Guide: https://tsdown.dev/guide/migrate-from-tsup

Illustrative Want to see what tsdown would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/2/2026, 15:32 UTC · 23 cases

Lift

+65%

100% vs 35%

Agent turns

1.0 vs 1.0

Tokens

+137%

4,417.74 vs 1,863.83

fail → pass · 15pass → pass · 8

Per-case results (23)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 I need to configure tsdown for a new npm library project. Please provide a `tsdown.config.ts` code snippet that outputs both ESM and CJS formats, generates TypeScript declaration files, empties the output folder before building, and ensures React is excluded from being bundled into the output.	fail→pass	4,671	3,899	-17%	1	1	0%	899	4,499	+400%	0	0	—
case-02 I am building a CLI tool written in TypeScript and want to generate standalone executables for Linux, macOS, and Windows. Could you show me how to structure my tsdown configuration file to target these three platforms with a specific Node version?	fail→pass	15,102	5,441	-64%	1	1	0%	2,856	4,839	+69%	0	0	—
case-03 We want to build a JavaScript library that runs on Node 18, but our build machine runs Node 22. How should we configure our library bundler setup so the build runs on Node 22 while target compatibility is set for Node 18?	fail→pass	13,630	7,374	-46%	1	1	0%	2,816	5,293	+88%	0	0	—
case-04 I am upgrading a library project that currently uses tsup to tsdown. Is there an automated CLI command provided by the ecosystem to convert my tsup setup?	fail→pass	7,799	15,172	+95%	1	1	0%	1,499	4,328	+189%	0	0	—
case-05 In my TypeScript library build configuration, I want to bundle only `cac` and `bumpp` into the output and leave all other node_modules dependencies as external. Which configuration key should I use for this whitelist behavior?	fail→pass	6,674	3,413	-49%	1	1	0%	1,214	4,172	+244%	0	0	—
case-06 I want my TypeScript library build configuration to run publint and attw package validation checks automatically when running in CI, but skip or avoid failing on them during local development builds. How can this be set in the build config?	fail→pass	11,764	4,166	-65%	1	1	0%	2,249	4,505	+100%	0	0	—
case-07 We have a utility library with dozens of files in `src/`. Rather than bundling everything into a single index file, we want to compile all `.ts` files into individual output files while preserving the `src/` directory structure in `dist/`. What option handles this in tsdown?	fail→pass	17,339	2,450	-86%	1	1	0%	2,271	4,224	+86%	0	0	—
case-08 When bundling a component library with tsdown that contains CSS styles, we want to preserve CSS imports directly inside the generated JavaScript output files instead of emitting a separate CSS file. What option in `css` config controls this?	fail→pass	22,116	2,364	-89%	1	1	0%	3,999	4,107	+3%	0	0	—
case-09 Our TypeScript library is compiled for both ESM and CJS formats, but inside the code we reference `__dirname` and `__filename`. When running in ESM mode, these variables cause runtime errors. What configuration option adds global compatibility wrappers for Node environment variables in tsdown?	pass→pass	6,170	2,855	-54%	1	1	0%	1,066	4,256	+299%	0	0	—
case-10 We want our tsdown build to complete without failing on local developer machines if there are minor build warnings, but we want CI pipeline builds to treat warnings as fatal errors. Which option value pair achieves this?	fail→pass	10,508	2,964	-72%	1	1	0%	1,995	4,216	+111%	0	0	—
case-11 We are organizing a monorepo with multiple packages under `packages/*`. How can we write a single `tsdown.config.ts` at the root that targets all packages in the workspace?	fail→pass	10,967	10,551	-4%	1	1	0%	2,235	4,747	+112%	0	0	—
case-12 How can I configure `tsdown.config.ts` dynamically so that minification is enabled during regular builds, but disabled during watch mode (`--watch`), while sourcemaps are enabled only during watch mode?	pass→pass	8,015	3,255	-59%	1	1	0%	1,576	4,306	+173%	0	0	—
case-13 I am bundling a TypeScript library that imports a WebAssembly (`.wasm`) module using tsdown. What plugin integration is recommended to support WASM modules?	fail→pass	10,757	3,462	-68%	1	1	0%	1,938	4,412	+128%	0	0	—
case-14 I need to run a custom asynchronous Node.js function immediately after tsdown finishes generating all bundle files. Which specific configuration property and hook name should I use in `tsdown.config.ts`?	fail→pass	12,835	2,908	-77%	1	1	0%	2,532	4,267	+69%	0	0	—
case-15 I need a `tsdown.config.ts` configuration to bundle a single file `src/index.ts` into a minified IIFE format for browsers, exposing the global variable name `MyLibrary`.	fail→pass	7,163	3,060	-57%	1	1	0%	1,409	4,361	+210%	0	0	—
case-16 Which configuration option in tsdown automatically generates or updates the `exports` field in `package.json` based on the output build artifacts?	pass→pass	12,535	2,194	-82%	1	1	0%	2,327	4,076	+75%	0	0	—
case-17 How do I inject SCSS global variables (e.g. `@use "src/styles/variables" as *;`) into every SCSS file compiled by tsdown?	pass→pass	10,676	4,975	-53%	1	1	0%	1,988	4,325	+118%	0	0	—
case-18 In a monorepo setup using tsdown, what CLI flags allow me to enable workspace mode and build only packages matching the name `my-package`?	fail→pass	5,643	2,247	-60%	1	1	0%	1,002	4,119	+311%	0	0	—
case-19 We are migrating a library build setup from Vite to tsdown. What CLI option allows tsdown to read and reuse settings directly from an existing `vite.config.ts`?	fail→pass	10,285	2,302	-78%	1	1	0%	1,975	4,003	+103%	0	0	—
case-20 I am creating a Next.js 14 App Router application and need to configure middleware to protect `/dashboard` routes. How do I export a middleware function and matcher config in `middleware.ts`?	pass→pass	10,268	5,646	-45%	1	1	0%	1,617	4,842	+199%	0	0	—
case-21 We use `@changesets/cli` for versioning our npm packages. What command sequence is used to create a new changeset entry, apply version bumps based on accumulated changesets, and publish to npm?	pass→pass	7,513	5,040	-33%	1	1	0%	1,315	4,651	+254%	0	0	—
case-22 I need to align items in a web navigation bar horizontally, with the logo on the left and navigation links spaced out on the right using standard CSS flexbox. What CSS properties should be applied to the navbar container?	pass→pass	6,751	5,374	-20%	1	1	0%	1,368	4,765	+248%	0	0	—
case-23 How do I configure Vitest in `vitest.config.ts` to use happy-dom environment and run test files matching `*.spec.ts`?	pass→pass	3,822	3,090	-19%	1	1	0%	722	4,295	+495%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 23 cases were attempted. The headline lift of +65 percentage points is the difference between those two pass rates over the 23 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 34.8%
Pass rate with the skill: 100%
Cases attempted: 23
Cases counted toward lift: 23
Cases that regressed: 0
Skill version measured: v2
Run completed: 8/2/2026, 15:32 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-01

Prompt

I need to configure tsdown for a new npm library project. Please provide a `tsdown.config.ts` code snippet that outputs both ESM and CJS formats, generates TypeScript declaration files, empties the output folder before building, and ensures React is excluded from being bundled into the output.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run100

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+197% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 51 days ago

Model	Method	Date	Lift
gemini-3.6-flash	verified	7/24/2026	+50%

Other measured skills in the registry, with their headline benchmark lift.