0
# tsdown
1
2
tsdown is a modern JavaScript/TypeScript bundler for libraries built on top of Rolldown (powered by Oxc). It serves as a high-performance alternative to tsup, offering blazing fast builds with declaration file generation, comprehensive plugin ecosystem support (Rollup, Rolldown, unplugin, and some Vite plugins), and zero-configuration setup for immediate productivity.
3
4
## Package Information
5
6
- **Package Name**: tsdown
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tsdown`
10
11
## Core Imports
12
13
```typescript
14
import { build, defineConfig } from "tsdown";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { build, defineConfig } = require("tsdown");
21
```
22
23
For plugins:
24
25
```typescript
26
import { ExternalPlugin, ShebangPlugin, ReportPlugin, NodeProtocolPlugin } from "tsdown/plugins";
27
```
28
29
For CLI usage:
30
31
```bash
32
npx tsdown [files]
33
```
34
35
## Basic Usage
36
37
```typescript
38
import { build, defineConfig } from "tsdown";
39
40
// Simple build with defaults
41
await build({
42
entry: "src/index.ts",
43
format: ["esm", "cjs"],
44
dts: true
45
});
46
47
// Using defineConfig for type safety
48
export default defineConfig({
49
entry: "src/index.ts",
50
format: ["esm", "cjs"],
51
outDir: "dist",
52
dts: true,
53
sourcemap: true,
54
clean: true
55
});
56
```
57
58
## Architecture
59
60
tsdown is built around several key components:
61
62
- **Core Build Engine**: Powered by Rolldown (Oxc) for maximum performance and modern JavaScript/TypeScript support
63
- **Configuration System**: Zero-config defaults with extensive customization options via defineConfig
64
- **Plugin Ecosystem**: Compatible with Rollup, Rolldown, unplugin, and select Vite plugins
65
- **TypeScript Integration**: Built-in TypeScript support with automatic declaration file generation
66
- **Workspace Support**: Monorepo and workspace capabilities for multi-package projects
67
- **CLI Interface**: Command-line tool with comprehensive options and migration utilities
68
- **Quality Assurance**: Integration with publint, Are The Types Wrong, and unused dependency checking
69
70
## Capabilities
71
72
### Core Build System
73
74
Main build functionality for bundling TypeScript/JavaScript libraries with Rolldown. Supports multiple output formats, TypeScript declaration generation, and extensive configuration options.
75
76
```typescript { .api }
77
function build(userOptions?: Options): Promise<void>;
78
79
interface Options {
80
entry?: InputOption;
81
format?: Format | Format[];
82
outDir?: string;
83
dts?: boolean | DtsOptions;
84
sourcemap?: boolean | 'inline' | 'hidden';
85
clean?: boolean | string[];
86
// ... extensive options interface
87
}
88
89
type Format = 'es' | 'cjs' | 'iife' | 'umd';
90
```
91
92
[Build System](./build-system.md)
93
94
### Configuration Management
95
96
Type-safe configuration system with defineConfig helper and extensive options for customizing the build process.
97
98
```typescript { .api }
99
function defineConfig(options: UserConfig): UserConfig;
100
function defineConfig(options: UserConfigFn): UserConfigFn;
101
102
type UserConfig = Arrayable<Omit<Options, 'config' | 'filter'>>;
103
type UserConfigFn = (cliOptions: Options) => Awaitable<UserConfig>;
104
```
105
106
[Configuration](./configuration.md)
107
108
### Plugin System
109
110
Built-in plugins for common bundling tasks and integration with external plugin ecosystems.
111
112
```typescript { .api }
113
function ExternalPlugin(options: ResolvedOptions): Plugin;
114
function ShebangPlugin(logger: Logger, cwd: string, name?: string, isMultiFormat?: boolean): Plugin;
115
function ReportPlugin(options: ReportOptions, logger: Logger, cwd: string, cjsDts?: boolean, name?: string, isMultiFormat?: boolean): Plugin;
116
function NodeProtocolPlugin(nodeProtocolOption: 'strip' | true): Plugin;
117
```
118
119
[Plugin System](./plugins.md)
120
121
### CLI Interface
122
123
Command-line interface with comprehensive options for building, watching, and managing projects.
124
125
```typescript { .api }
126
function runCLI(): Promise<void>;
127
```
128
129
Available CLI commands:
130
- `tsdown [files]` - Build command with extensive options
131
- `tsdown migrate` - Migration utility from tsup to tsdown
132
133
[CLI Interface](./cli.md)
134
135
### Workspace Support
136
137
Multi-package support for monorepos with filtering and configuration management.
138
139
```typescript { .api }
140
interface Workspace {
141
include?: Arrayable<string> | 'auto';
142
exclude?: Arrayable<string>;
143
config?: boolean | string;
144
}
145
```
146
147
[Workspace Support](./workspace.md)
148
149
### Migration Tools
150
151
Built-in migration utilities for moving from tsup to tsdown with automatic configuration conversion.
152
153
```typescript { .api }
154
function migrate(options: { cwd?: string; dryRun?: boolean }): Promise<void>;
155
```
156
157
[Migration Tools](./migration.md)
158
159
## Types
160
161
```typescript { .api }
162
// Core types
163
type Sourcemap = boolean | 'inline' | 'hidden';
164
type Format = 'es' | 'cjs' | 'iife' | 'umd';
165
type NormalizedFormat = 'es' | 'cjs' | 'iife' | 'umd';
166
167
// Platform and target types
168
type Platform = 'node' | 'neutral' | 'browser';
169
170
// Module types for file processing
171
type ModuleTypes = Record<string, 'js' | 'jsx' | 'ts' | 'tsx' | 'json' | 'text' | 'base64' | 'dataurl' | 'binary' | 'empty' | 'css' | 'asset'>;
172
173
// Logging types
174
type LogLevel = 'silent' | 'error' | 'warn' | 'info';
175
176
interface Logger {
177
info(...args: any[]): void;
178
warn(...args: any[]): void;
179
error(...args: any[]): void;
180
success(...args: any[]): void;
181
}
182
183
// Utility types
184
type Arrayable<T> = T | T[];
185
type Awaitable<T> = T | Promise<T>;
186
```