tsdown Documentation

tsdown is a high-performance bundler for libraries powered by Rolldown and Oxc. Key features include:

• Blazing fast: High-speed builds and declaration file generation.
• Powerful ecosystem: Supports Rollup, Rolldown, unplugin plugins, and select Vite plugins.
• Easy to use: Preconfigured for immediate use.
• Seamless migration: Compatible with tsup options and features for easy transitions.

tsdown is an elegant library bundler designed specifically for TypeScript and JavaScript library authors. Built on top of the Rust-based Rolldown engine, it provides a complete out-of-the-box solution that simplifies the bundling process compared to general-purpose bundlers.

Key capabilities include:

• TypeScript & JavaScript: Seamless bundling of .ts and .js files.
• Automatic Declarations: Automatic generation of .d.ts files.
• Multiple Formats: Support for esm, cjs, iife, and umd output formats.
• Asset Support: Processing of .json and .wasm files.
• Optimizations: Built-in support for tree shaking, minification, and source maps.

tsdown provides several automated features tailored for library development:

• Simplified Configuration: Sensible defaults with minimal boilerplate.
• Automatic Externalization: Automatically treats dependencies, peerDependencies, and optionalDependencies from your package.json as external.
• TypeScript Support: Auto-generates .d.ts declaration files.
• Output Formats: Supports esm, cjs, iife, and umd.
• Asset Support: Bundles .json, .wasm, and CSS files.
• Package Integration: Generates the exports field for package.json.
• Advanced Bundling: Includes tree shaking, minification, source maps, and a CSS preprocessing pipeline.
• Executable Bundling: Supports Single Executable Applications (SEA).

The @tsdown/css package, powered by Lightning CSS, provides the following capabilities for tsdown users:

• CSS extraction and bundling: Automatically handles CSS files during the build process.
• CSS @import inlining: Uses Lightning CSS bundleAsync to inline imports.
• Syntax lowering and autoprefixing: Ensures compatibility across different browsers.
• Minification: Reduces CSS file size for production.
• Code splitting: Optimizes CSS delivery.
• Source map support: Enables easier debugging of CSS.
• Preprocessor support: Handles Sass, Less, and Stylus.
• PostCSS integration: Allows for extensible CSS transformations.

Compared to tsup, tsdown provides several new capabilities:

• nodeProtocol: Control Node.js built-in module imports (true adds node: prefix, 'strip' removes it, false keeps as-is).
• workspace: Build multiple packages in a monorepo (e.g., workspace: 'packages/*').
• exports: Auto-generate the exports field in package.json via exports: true.
• publint / attw: Validate packages for common issues.
• exe: Bundle as a Node.js standalone executable via exe: true.
• devtools: Enable Vite DevTools for bundle analysis via devtools: true.
• hooks: Lifecycle hooks: build:prepare, build:before, and build:done.
• css: Full CSS pipeline (preprocessors, Lightning CSS, PostCSS, etc.).
• globImport: Support for import.meta.glob (Vite-style).

By default, tsdown handles dependencies based on their classification in package.json:

• dependencies, peerDependencies, and optionalDependencies: These are treated as external and are not bundled. They are expected to be provided by the consumer's environment.
• devDependencies and Phantom Dependencies (packages in node_modules not in package.json): These are bundled only if they are actually imported or required by your source code.

The speed of .d.ts generation depends on your tsconfig.json settings:

• High Performance: Enable isolatedDeclarations: true in your tsconfig.json. This allows tsdown to use oxc-transform, which is extremely fast.
• Standard Performance: If isolatedDeclarations is not enabled, tsdown falls back to the standard TypeScript compiler, which is slower.

// Recommended for speed
{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}