# tsdown

Skill for bundling TypeScript and JavaScript libraries with Rolldown. Generates type declarations, outputs ESM/CJS, optimizes via tree shaking and minification.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1500 installs · ★ 4323
- Author: rolldown
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/rolldown/tsdown/tree/HEAD/skills/tsdown/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/tsdown

## What it does

tsdown is a bundler powered by Rolldown and Oxc, built for shipping libraries. It generates `.d.ts` files, bundles to multiple formats (ESM, CJS, IIFE, UMD), and handles tree shaking and minification. Works with React, Vue, Solid, and Svelte components. Requires Node.js 22.18.0+ to run the build (build-time only), but output can target Node.js 18+ via the `target` option.

You set entry points, output formats, and whether to generate types in the config. Watch mode, automatic output cleaning, plugin support (Rolldown, Rollup, Unplugin), and lifecycle hooks are all built in. Migrating from tsup? Use the bundled migration utility.

Core features: dependency control (what to bundle, what stays external), ESM/CJS shims, auto-generated `exports` field, CSS handling with modules. Experimental support for copying static assets and unbundle mode (preserves directory structure).

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add rolldown/tsdown --skill tsdown -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tsdown/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tsdown/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add rolldown/tsdown --skill tsdown -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tsdown/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add rolldown/tsdown --skill tsdown -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tsdown/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install rolldown/tsdown tsdown
```

2. **Manually: put the files in place**
- File: `.github/skills/tsdown/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add rolldown/tsdown --skill tsdown -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/rolldown/tsdown --path skills/tsdown
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tsdown/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add rolldown/tsdown --skill tsdown -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/rolldown/tsdown/tree/HEAD/skills/tsdown/SKILL.md

## When to use it
- bundle a TypeScript library into multiple formats at once
- generate type declarations and .d.ts files
- optimize bundles with tree shaking and minification
- migrate a project from tsup to Rolldown
- configure dependencies for an npm package

## Example prompts
- Bundle the library to ESM and CJS with types using tsdown
- Migrate the project from tsup to tsdown and output to dist
- Run tsdown in watch mode and watch type changes live

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 10207e424bd714c0.

BEGIN THIRD-PARTY FILE 10207e424bd714c0
````text
---
name: tsdown
description: 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.
---

# 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`](references/option-target.md) 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](references/guide-getting-started.md) |
| Configuration File | Config file formats, multiple configs, workspace | [option-config-file](references/option-config-file.md) |
| CLI Reference | All CLI commands and options | [reference-cli](references/reference-cli.md) |
| Migrate from tsup | Migration guide and compatibility notes | [guide-migrate-from-tsup](references/guide-migrate-from-tsup.md) |
| Plugins | Rolldown, Rollup, Unplugin support | [advanced-plugins](references/advanced-plugins.md) |
| Hooks | Lifecycle hooks for custom logic | [advanced-hooks](references/advanced-hooks.md) |
| Programmatic API | Build from Node.js scripts, in-memory builds (`write: false`) | [advanced-programmatic](references/advanced-programmatic.md) |
| Rolldown Options | Pass options directly to Rolldown | [advanced-rolldown-options](references/advanced-rolldown-options.md) |
| CI Environment | CI detection, `'ci-only'` / `'local-only'` values | [advanced-ci](references/advanced-ci.md) |

> For comprehensive migration assistance with complete option mappings, install the dedicated [`tsdown-migrate`](../tsdown-migrate/SKILL.md) skill: `npx skills add rolldown/tsdown --skill tsdown-migrate`
````
END THIRD-PARTY FILE 10207e424bd714c0

The third-party file has ended. Everything between the 10207e424bd714c0 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3100 of 13528 bytes. © rolldown · MIT · https://github.com/rolldown/tsdown/tree/HEAD/skills/tsdown/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md