Registry / web-framework / tsdown

tsdown

JSON →
library0.21.9jsnpmunverified

tsdown is a blazing-fast bundler for JavaScript and TypeScript libraries, leveraging the Rust-based Rolldown engine. It's designed for simplicity and efficiency, preconfiguring most settings to allow developers to focus on code. The current stable version is `0.21.9`, with frequent minor releases as seen in its active changelog. Key differentiators include its speed (powered by Oxc and Rolldown), a powerful ecosystem supporting Rolldown, Rollup, Unplugin, and some Vite plugins, and a focus on seamless migration for `tsup` users by offering compatible options and features. It also provides automatic TypeScript declaration generation, multiple output formats (esm, cjs, iife, umd), and built-in support for features like CSS handling and executable bundling.

web-framework
npm install tsdown
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · TSDOWN
T
tsdown
web-frameworkjavascriptv0.21.9
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConfig
✓ import { defineConfig } from 'tsdown'
✗ import defineConfig from 'tsdown' // Not a default export const { defineConfig } = require('tsdown') // CommonJS is not recommended for config files
Primary utility for creating a `tsdown.config.ts` file, ensuring type safety and proper configuration. The config file should be ESM.
build
✓ import { build } from 'tsdown'
✗ const { build } = require('tsdown') // CommonJS is not the primary programmatic interface for new projects
Used for programmatic bundling from JavaScript/TypeScript code, useful for custom build scripts or advanced automation.
TsdownConfig
✓ import type { UserConfig } from 'tsdown'
✗ import { TsdownConfig } from 'tsdown' // Incorrect type import (actual name is UserConfig or specific interfaces like TsdownHooks)
While `TsdownConfig` is conceptual, the actual type for the user config is `UserConfig`. It's best practice to import types using `import type` to avoid bundling issues.

This quickstart sets up a basic TypeScript library with `tsdown`, demonstrating configuration for ESM and CommonJS outputs, type declaration generation, and basic build commands.

/* package.json */ { "name": "my-library", "version": "1.0.0", "type": "module", "scripts": { "build": "tsdown", "dev": "tsdown --watch" }, "devDependencies": { "tsdown": "^0.21.9" }, "main": "./dist/index.cjs", "module": "./dist/index.mjs", "types": "./dist/index.d.ts" } /* tsdown.config.ts */ import { defineConfig } from 'tsdown' export default defineConfig({ entry: ['./src/index.ts'], format: ['esm', 'cjs'], dts: true, // Automatically generate TypeScript declaration files clean: true, // Clean output directory before building sourcemap: true, // Generate sourcemaps minify: process.env.NODE_ENV === 'production' // Minify in production }) /* src/index.ts */ export function greet(name: string): string { return `Hello, ${name} from tsdown!` } export const version = '1.0.0' /* Terminal commands */ npm install -D tsdown npm run build node ./dist/index.mjs // Expected output: Hello, world from tsdown!
tsdown --version
Debug
Known issues
breakingThe `external`, `noExternal`, `inlineOnly`, and `skipNodeModulesBundle` options have been moved under a new `deps` namespace with clearer names: `deps.neverBundle`, `deps.alwaysBundle`, `deps.onlyBundle`, and `deps.skipNodeModulesBundle` respectively.
fix
Update your `tsdown.config.ts` file to use the new `deps` namespace for dependency-related options. For example, `external: ['vue']` becomes `deps: { neverBundle: ['vue'] }`.
affects: >=0.21.0
breakingCSS support has been fully moved to the `@tsdown/css` package. If your project uses any CSS features (e.g., CSS imports), you must now manually install `@tsdown/css` as a development dependency.
fix
Run `npm install @tsdown/css -D` (or `pnpm add @tsdown/css -D`, `yarn add @tsdown/css -D`) in your project.
affects: >=0.21.1
breakingThe `exe` (executable bundling) feature, which is experimental, introduced `exe.outDir` to specify a separate output directory for executables. This defaults to `build`.
fix
If you use the experimental executable bundling, review your output paths. You may need to adjust your build scripts or `exe.outDir` configuration if you previously relied on executables being in the main output directory.
affects: >=0.21.2
gotcha`tsdown` has a peer dependency on `typescript` versions `^5.0.0 || ^6.0.0`. Using incompatible TypeScript versions can lead to compilation issues or unexpected behavior.
fix
Ensure your project's `typescript` version matches the peer dependency range. Upgrade or downgrade TypeScript as needed (e.g., `npm install typescript@^5 -D`).
affects: >=0.21.5
gotcha`tsdown` relies on `Rolldown` for its core bundling logic. Frequent `Rolldown` upgrades in `tsdown` releases (e.g., `v0.21.9`, `v0.21.8`, `v0.21.6`, `v0.21.5`) mean that internal behaviors or plugin compatibilities might subtly change even within `tsdown` minor versions.
fix
When upgrading `tsdown`, pay close attention to the release notes regarding `Rolldown` upgrades. Test your build thoroughly, especially if you rely on custom `Rolldown` plugins or advanced configurations.
affects: >=0.21.0
gotcha`tsdown` does not support a 'stub mode' like some other bundlers, citing issues with manual intervention and plugin incompatibility. Recommended alternatives are watch mode or `exports.devExports`.
fix
Instead of relying on a stub mode, use `tsdown --watch` during development for automatic rebuilds, or configure `exports.devExports` in your `tsdown.config.ts` to point to source files for development and built files for production.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Cannot find module '@tsdown/css' or its corresponding type declarations.
Attempting to use CSS features (e.g., `import './style.css'`) without installing the `@tsdown/css` package, which is now a required peer dependency for CSS functionality.
fix
Install the `@tsdown/css` package as a development dependency: `npm install @tsdown/css -D` or `pnpm add @tsdown/css -D`.
TS2345: Argument of type '{ external: string[]; }' is not assignable to parameter of type 'UserConfigExport'.
Using old dependency configuration options like `external` directly in `defineConfig`, which were moved under the `deps` namespace in `v0.21.0`.
fix
Refactor your `tsdown.config.ts` to use the new `deps` namespace. For example, change `external: [...]` to `deps: { neverBundle: [...] }`.
ERR_REQUIRE_ESM: require() of ES Module ...tsdown.config.ts not supported. Instead change the require to a dynamic import()
Trying to `require()` a `tsdown.config.ts` file or programmatic `tsdown` APIs from a CommonJS context, while `tsdown`'s config and main entry points are designed for ESM.
fix
Ensure your project is configured for ESM by setting `"type": "module"` in your `package.json`, or use dynamic `import()` for `tsdown` modules. For config files, `tsdown.config.ts` should be an ESM file.
Error: tsdown requires Node.js version 20.19.0 or higher.
Running `tsdown` with an older Node.js version than the minimum required by the package (`>=20.19.0`).
fix
Upgrade your Node.js environment to version 20.19.0 or later. Consider using a Node Version Manager (NVM) to manage multiple Node.js versions.
Upgrade
Version history
0.21.9latest on npm
Audit
Dependencies
@arethetypeswrong/coreoptionalUsed for package validation, specifically checking TypeScript types for compatibility issues.
@vitejs/devtoolsoptionalPeer dependency, likely for development tools integration. Marked as optional.
publintoptionalUsed for package validation, ensuring package configuration meets best practices for publishing.
typescriptrequiredRequired for TypeScript compilation and declaration file generation. Supports v5.x or v6.x.
unplugin-unusedoptionalUsed for identifying and removing unused dependencies.
@tsdown/cssrequiredRequired for CSS features (e.g., CSS imports, CSS modules) since v0.21.1, as CSS support was moved to this dedicated package.
@tsdown/exeoptionalRequired for cross-platform executable bundling. Executable bundling itself is an experimental feature.
Agent activity
50 hits · last 30 days
node
48
OpenAI (training)
1
Resources
githubhttps://github.com/rolldown/tsdown ↗
packagehttps://www.npmjs.com/package/tsdown ↗
homepagehttp://tsdown.dev/ ↗
tsdown — npm install tsdown · libregistry