tsdown_skill

Overview

This skill describes tsdown, a next-generation TypeScript library bundler built on Rolldown and Oxc. It emphasizes blazing-fast builds, pure-ESM outputs, automatic .d.ts generation, and smooth migration from tsup. The tool supports Rolldown/Rollup/Unplugin plugins and smart dependency handling for library authors.

How this skill works

tsdown reads a configuration file or CLI options to determine entry points, output formats, and build options. It leverages Oxc for fast TypeScript compilation and Rolldown for bundling, producing ESM artifacts and emitted declaration files when dts is enabled. It can run in bundle or unbundle (transpile-only) modes, and exposes hooks and a programmatic API for custom workflows.

When to use it

• When building TypeScript libraries that must ship as pure ESM packages.
• When you need automatic generation of .d.ts declaration files alongside builds.
• When migrating a project from tsup and wanting faster builds with similar ergonomics.
• When you need fine-grained control over entry points, exports, and dependency handling.
• When integrating Rolldown/Rollup or Unplugin plugins into a library build pipeline.

Best practices

• Prefer pure-ESM outputs and avoid producing CJS unless required by downstream consumers.
• Always enable the dts option to generate .d.ts files and keep TypeScript types in sync.
• Enable exports option to auto-generate package exports and keep package.json fields consistent.
• Use explicit entry point globs or aliases to control public surface area and tree shaking.
• Mark heavy runtime dependencies as external or use noExternal selectively to optimize bundle size.

Example use cases

• Building a reusable React or Vue component library with ESM bundles and type declarations.
• Converting an existing tsup-based library to tsdown for faster incremental builds.
• Publishing a small utility library that requires precise package exports and typings.
• Setting up a monorepo build where multiple entry configs and watch mode speed development.
• Creating an unbundle (transpile-only) workflow for type checking and source distribution.