Agent skill

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.

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/antfu/tsdown

SKILL.md

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

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
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: 'ci-only' option-log-level

Dependency Handling

Feature Usage Reference
External deps external: ['react', /^@myorg\//] option-dependencies
Inline deps noExternal: ['dep-to-bundle'] 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] Still in development option-css
Unbundle mode unbundle: true - Preserve directory structure option-unbundle
Package validation publint: true, attw: true - Validate package option-lint

Framework & Runtime Support

Framework Guide Reference
React JSX transform, Fast Refresh recipe-react
Vue SFC support, JSX recipe-vue
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,
  external: ['react', 'react-dom'],
  plugins: [
    // React Fast Refresh support
  ],
})

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

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 --outDir lib            # Custom output directory
tsdown --minify                # Enable minification
tsdown --dts                   # Generate declarations

# Entry options
tsdown src/index.ts            # Single entry
tsdown src/*.ts                # Glob patterns
tsdown src/a.ts src/b.ts       # Multiple entries

# Development
tsdown --watch                 # Watch mode
tsdown --sourcemap             # Generate source maps
tsdown --clean                 # Clean output directory

Best Practices

  1. Always generate type declarations for TypeScript libraries:

    ts
    { dts: true }

  2. Externalize dependencies to avoid bundling unnecessary code:

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

  3. Use tree shaking for optimal bundle size:

    ts
    { treeshake: true }

  4. Enable minification for production builds:

    ts
    { minify: true }

  5. Add shims for better ESM/CJS compatibility:

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

  6. Auto-generate package.json exports:

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

  7. Use watch mode during development:

    bash
    tsdown --watch

  8. Preserve structure for utilities with many files:

    ts
    { unbundle: true }  // Keep directory structure

  9. Validate packages in CI before publishing:

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

Resources

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results