Tsdown

JetBrainsOfficialCreated by Anthony FuDistributed by JetBrains

Skill
Tool integration
Software development
MIT
No issues found

From the author

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 description by Anthony Fu

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

tsdown is a library bundler designed for TypeScript and JavaScript projects. It leverages Rolldown and Oxc to handle bundling tasks, including generating type declarations, supporting multiple output formats, and managing dependencies. It provides a configuration-driven approach to library development, supporting various frameworks and runtime environments, and includes a migration path for users moving from tsup.

What it does

Bundles TypeScript and JavaScript libraries into multiple formats like ESM, CJS, IIFE, and UMD.
Generates TypeScript declaration files (.d.ts) automatically.
Supports dependency management, including externalization and bundling options.
Provides hooks for custom build logic and supports plugins from the Rolldown and Rollup ecosystems.
Offers specialized configurations for component libraries using React, Vue, Solid, or Svelte.
Includes a migration tool to assist with transitioning from tsup.

When to use it

When building TypeScript or JavaScript libraries for distribution via npm.
When you need to generate type declarations alongside your bundled code.
When your project requires bundling for multiple module formats.
When migrating an existing library project from tsup.
When developing component libraries for frameworks like React, Vue, or Svelte.

Advantages

Simplifies the bundling process for library authors with a clear configuration API.
Provides built-in support for common library tasks like package exports and ESM/CJS shims.
Offers CI-aware configuration options to validate packages before publishing.
Supports advanced features like standalone executable bundling and CSS processing.
Allows for flexible build configurations including monorepo and workspace support.

Usage examples

“How do I bundle my TypeScript library for both ESM and CJS formats?”: You can use a tsdown.config.ts file with the format option set to ['esm', 'cjs'] and dts set to true to generate declarations.
“How can I migrate my existing tsup project to tsdown?”: You can run the npx tsdown-migrate command to assist with the transition.
“How do I configure tsdown to exclude React from my bundle?”: In your configuration file, use the deps.neverBundle option to specify ['react', 'react-dom'].
“How do I enable watch mode for development?”: Run the command npx tsdown --watch to enable watch mode for your build process.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/jetbrains/tsdown/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip tsdown.zip -d .agents/skills
```

Documentation by Anthony Fu

tsdown - The Elegant Library Bundler

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

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

# 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

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

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 peer/dependency 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` - Auto-generate exports field	option-package-exports
CSS handling	[experimental] `css: { ... }` — full pipeline with preprocessors, Lightning CSS, PostCSS, code splitting; requires `@tsdown/css`	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

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

Multiple Entry Points

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)

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

React Component Library

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

Preserve Directory Structure

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

CI-Aware Configuration

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

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

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

Library with CSS and Sass

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

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

Cross-Platform Executable (requires `@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' },
    ],
  },
})

Advanced with Hooks

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:

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:

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:

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

CLI Quick Reference

# 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:
```
{ 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 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' }
```

Resources

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

Files

ATTRIBUTION.mdAdded by AutoGineer870 B
LICENSE.md1.1 KiB
README.md1.9 KiB
SKILL.md11.7 KiB
SYNC.md140 B
references/README.md4.7 KiB
references/advanced-benchmark.md265 B
references/advanced-ci.md2.0 KiB
references/advanced-hooks.md6.9 KiB
references/advanced-plugins.md6.6 KiB
references/advanced-programmatic.md5.9 KiB
references/advanced-rolldown-options.md2.3 KiB
references/guide-getting-started.md2.6 KiB
references/guide-introduction.md1.5 KiB
references/guide-migrate-from-tsup.md4.2 KiB
references/option-cjs-default.md1.9 KiB
references/option-cleaning.md4.8 KiB
references/option-config-file.md5.1 KiB
references/option-css.md5.5 KiB
references/option-dependencies.md7.3 KiB
references/option-dts.md4.5 KiB
references/option-entry.md3.6 KiB
references/option-exe.md3.3 KiB
references/option-lint.md2.9 KiB
references/option-log-level.md1.8 KiB
references/option-minification.md3.5 KiB
references/option-output-directory.md4.4 KiB
references/option-output-format.md3.4 KiB
references/option-package-exports.md5.2 KiB
references/option-platform.md5.1 KiB
references/option-root.md1.8 KiB
references/option-shims.md5.5 KiB
references/option-sourcemap.md5.4 KiB
references/option-target.md4.0 KiB
references/option-tree-shaking.md5.1 KiB
references/option-unbundle.md5.5 KiB
references/option-watch-mode.md4.6 KiB
references/recipe-react.md5.9 KiB
references/recipe-solid.md929 B
references/recipe-svelte.md1.4 KiB
references/recipe-vue.md6.4 KiB
references/recipe-wasm.md2.6 KiB
references/reference-cli.md7.3 KiB

references/reference-cli.md

CLI Reference

Complete reference for tsdown command-line interface.

Overview

All CLI flags can also be set in the config file. CLI flags override config file options.

Flag Patterns

CLI flag mapping rules:

--foo sets foo: true
--no-foo sets foo: false
--foo.bar sets foo: { bar: true }
--format esm --format cjs sets format: ['esm', 'cjs']

CLI flags support both camelCase and kebab-case. For example, --outDir and --out-dir are equivalent.

Basic Commands

Build

# Build with default config
tsdown

# Build specific files
tsdown src/index.ts src/cli.ts

# Build with watch mode
tsdown --watch

Configuration

`--config, -c <filename>`

Specify custom config file:

tsdown --config build.config.ts
tsdown -c custom-config.js

`--no-config`

Disable config file loading:

tsdown --no-config src/index.ts

`--config-loader <loader>`

Choose config loader (auto, native, unrun):

tsdown --config-loader unrun

`--tsconfig <file>`

Specify TypeScript config file:

tsdown --tsconfig tsconfig.build.json

Entry Points

`[...files]`

Specify entry files as arguments:

tsdown src/index.ts src/utils.ts

Output Options

`--format <format>`

Output format (esm, cjs, iife, umd):

tsdown --format esm
tsdown --format esm --format cjs

`--out-dir, -d <dir>`

Output directory:

tsdown --out-dir lib
tsdown -d dist

`--dts`

Generate TypeScript declarations:

tsdown --dts

`--clean`

Clean output directory before build:

tsdown --clean

Build Options

`--target <target>`

JavaScript target version:

tsdown --target es2020
tsdown --target node18
tsdown --target chrome100
tsdown --no-target  # Disable transformations

`--platform <platform>`

Target platform (node, browser, neutral):

tsdown --platform node
tsdown --platform browser

`--minify`

Enable minification:

tsdown --minify
tsdown --no-minify

`--sourcemap`

Generate source maps:

tsdown --sourcemap
tsdown --sourcemap inline

`--treeshake`

Enable/disable tree shaking:

tsdown --treeshake
tsdown --no-treeshake

Dependencies

`--deps.never-bundle <module>`

Mark module as external (not bundled):

tsdown --deps.never-bundle react --deps.never-bundle react-dom

`--deps.skip-node-modules-bundle`

Skip resolving and bundling all node_modules:

tsdown --deps.skip-node-modules-bundle

`--shims`

Add ESM/CJS compatibility shims:

tsdown --shims

Development

`--watch, -w [path]`

Enable watch mode:

tsdown --watch
tsdown -w
tsdown --watch src  # Watch specific directory

`--ignore-watch <path>`

Ignore paths in watch mode:

tsdown --watch --ignore-watch test

`--on-success <command>`

Run command after successful build:

tsdown --watch --on-success "echo Build complete!"

Environment Variables

`--env.* <value>`

Set compile-time environment variables:

tsdown --env.NODE_ENV=production --env.API_URL=https://api.example.com

Access as import.meta.env.* or process.env.*.

`--env-file <file>`

Load environment variables from file:

tsdown --env-file .env.production

`--env-prefix <prefix>`

Filter environment variables by prefix (default: TSDOWN_):

tsdown --env-file .env --env-prefix APP_ --env-prefix TSDOWN_

Assets

`--copy <dir>`

Copy directory to output:

tsdown --copy public
tsdown --copy assets --copy static

Executable

`--exe`

[experimental] Bundle as a standalone executable using Node.js Single Executable Applications. Requires Node.js >= 25.5.0, not supported in Bun or Deno. Cross-platform builds supported via @tsdown/exe.

tsdown --exe

When enabled:

Default format changes to cjs (unless Node.js >= 25.7.0)
Declaration file generation (dts) is disabled by default
Code splitting is disabled
Only single entry points are supported

See Executable for advanced configuration and cross-platform builds.

Package Management

`--exports`

Auto-generate package.json exports field:

tsdown --exports

`--publint`

Enable package validation:

tsdown --publint

`--attw`

Enable "Are the types wrong" validation:

tsdown --attw

`--unused`

Check for unused dependencies:

tsdown --unused

Logging

`--log-level <level>`

Set logging verbosity (silent, error, warn, info):

tsdown --log-level error
tsdown --log-level warn

`--report` / `--no-report`

Enable/disable build report:

tsdown --no-report  # Disable size report
tsdown --report     # Enable (default)

`--debug [feat]`

Show debug logs:

tsdown --debug
tsdown --debug rolldown  # Debug specific feature

Integration

`--from-vite [vitest]`

Extend Vite or Vitest config:

tsdown --from-vite         # Use vite.config.*
tsdown --from-vite vitest  # Use vitest.config.*

Workspace / Monorepo

`--workspace, -W [dir]`

Enable workspace mode for building multiple packages:

tsdown -W
tsdown -W packages/

`--filter, -F <pattern>`

Filter configs by name or working directory. Supports regex:

tsdown -W -F my-package
tsdown -W -F /^pkg-/

`--unbundle`

Enable unbundle (bundleless) mode:

tsdown --unbundle

`--root <dir>`

Specify the root directory of input files (similar to TypeScript's rootDir). Controls the output directory structure by determining how entry file paths map to output paths. Defaults to the common base directory of all entry files.

tsdown --root src
tsdown --root .

`--fail-on-warn`

Fail on warnings (enabled by default):

tsdown --no-fail-on-warn  # Disable

Common Usage Patterns

Basic Build

tsdown

Library (ESM + CJS + Types)

tsdown --format esm --format cjs --dts --clean

Production Build

tsdown --minify --clean --no-report

Development (Watch)

tsdown --watch --sourcemap

Browser Bundle (IIFE)

tsdown --format iife --platform browser --minify

Node.js CLI Tool

tsdown --format esm --platform node --shims

Standalone Executable

tsdown src/cli.ts --exe

Monorepo Package

tsdown --clean --dts --exports --publint

With Environment Variables

tsdown --env-file .env.production --env.BUILD_TIME=$(date +%s)

Copy Assets

tsdown --copy public --copy assets --clean

Tips

Use config file for complex setups
CLI flags override config file options
Chain multiple formats for multi-target builds
Use --clean to avoid stale files
Enable --dts for TypeScript libraries
Use --watch during development
Add --on-success for post-build tasks
Use --exports to auto-generate package.json fields

Config File - Configuration file options
Entry - Entry point configuration
Output Format - Format options
Watch Mode - Watch mode details

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Anthony Fu

Publisher

JetBrains (Official)

Distributed by

JetBrains

Source

JetBrains/skills · tsdown · commit 3f53782

Licence

MIT License (redistribution allowed)

ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Anthony Fu or JetBrains.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download tsdown.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Anthony Fu

tsdown - The Elegant Library Bundler

When to Use

Quick Start

Basic Configuration

Core References

Build Options

Dependency Handling

Output Enhancement

Framework & Runtime Support

Common Patterns

Basic Library Bundle

Multiple Entry Points

Browser Library (IIFE/UMD)

React Component Library

Preserve Directory Structure

CI-Aware Configuration

WASM Support

Library with CSS and Sass

Standalone Executable

Cross-Platform Executable (requires @tsdown/exe)

Advanced with Hooks

Configuration Features

Multiple Configs

Conditional Config

Workspace/Monorepo

CLI Quick Reference

Best Practices

Resources

Files

references/reference-cli.md

CLI Reference

Overview

Flag Patterns

Basic Commands

Build

Configuration

--config, -c <filename>

--no-config

--config-loader <loader>

--tsconfig <file>

Entry Points

[...files]

Output Options

--format <format>

--out-dir, -d <dir>

--dts

--clean

Build Options

--target <target>

--platform <platform>

--minify

--sourcemap

--treeshake

Dependencies

--deps.never-bundle <module>

--deps.skip-node-modules-bundle

--shims

Development

--watch, -w [path]

--ignore-watch <path>

--on-success <command>

Environment Variables

--env.* <value>

--env-file <file>

--env-prefix <prefix>

Assets

--copy <dir>

Executable

--exe

Package Management

--exports

--publint

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

`--config, -c <filename>`

`--no-config`

`--config-loader <loader>`

`--tsconfig <file>`

`[...files]`

`--format <format>`

`--out-dir, -d <dir>`

`--dts`

`--clean`

`--target <target>`

`--platform <platform>`

`--minify`

`--sourcemap`

`--treeshake`

`--deps.never-bundle <module>`

`--deps.skip-node-modules-bundle`

`--shims`

`--watch, -w [path]`

`--ignore-watch <path>`

`--on-success <command>`

`--env.* <value>`

`--env-file <file>`

`--env-prefix <prefix>`

`--copy <dir>`

`--exe`

`--exports`

`--publint`

`--attw`

`--unused`

`--log-level <level>`

`--report` / `--no-report`

`--debug [feat]`

`--from-vite [vitest]`

`--workspace, -W [dir]`

`--filter, -F <pattern>`

`--unbundle`

`--root <dir>`

`--fail-on-warn`