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
```