0
# CLI Interface
1
2
Command-line interface with comprehensive options for building, watching, and managing projects. The CLI provides extensive configuration options, debug capabilities, and migration utilities for seamless development workflows.
3
4
## Capabilities
5
6
### CLI Runner
7
8
Main CLI execution function that handles command parsing and execution.
9
10
```typescript { .api }
11
/**
12
* Run the tsdown CLI with command-line arguments
13
*/
14
function runCLI(): Promise<void>;
15
```
16
17
**Basic Usage:**
18
19
```bash
20
# Build with defaults
21
npx tsdown
22
23
# Build specific files
24
npx tsdown src/index.ts src/cli.ts
25
26
# Build with options
27
npx tsdown --format esm,cjs --dts --sourcemap
28
29
# Watch mode
30
npx tsdown --watch
31
32
# Debug mode
33
npx tsdown --debug
34
```
35
36
### Build Command
37
38
Main build command with extensive configuration options.
39
40
```bash
41
tsdown [files...] [options]
42
```
43
44
#### Input Options
45
46
```bash
47
# Entry files
48
tsdown src/index.ts src/cli.ts
49
50
# Configuration
51
-c, --config <filename> # Use custom config file
52
--no-config # Disable config file
53
54
# External dependencies
55
--external <module> # Mark dependencies as external
56
57
# Source processing
58
--tsconfig <tsconfig> # Set tsconfig path
59
--from-vite [vitest] # Reuse config from Vite or Vitest
60
```
61
62
#### Output Options
63
64
```bash
65
# Format and output
66
-f, --format <format> # Bundle format: esm, cjs, iife, umd (default: esm)
67
-d, --out-dir <dir> # Output directory (default: dist)
68
69
# Code generation
70
--dts # Generate TypeScript declaration files
71
--sourcemap # Generate source maps (default: false)
72
--minify # Minify output code
73
74
# Build behavior
75
--clean # Clean output directory
76
--no-clean # Disable cleaning output directory
77
--unbundle # Unbundle mode (mirror input structure)
78
```
79
80
#### Development Options
81
82
```bash
83
# Build target and platform
84
--target <target> # Bundle target (e.g., es2015, esnext, node18)
85
--platform <platform> # Target platform: node, neutral, browser (default: node)
86
87
# Tree-shaking and optimization
88
--treeshake # Enable tree-shaking (default: true)
89
--shims # Enable CJS and ESM shims (default: false)
90
91
# Environment
92
--env.* <value> # Define compile-time env variables
93
--on-success <command> # Command to run on success
94
```
95
96
#### Watch and Development
97
98
```bash
99
# Watch mode
100
-w, --watch [path] # Enable watch mode
101
--ignore-watch <path> # Ignore custom paths in watch mode
102
103
# Debugging
104
--debug [feat] # Show debug logs (tsdown:* or specific features)
105
```
106
107
#### Quality Assurance
108
109
```bash
110
# Linting and validation
111
--publint # Enable publint (default: false)
112
--attw # Enable Are The Types Wrong (default: false)
113
--unused # Enable unused dependencies check (default: false)
114
115
# Reporting
116
--report # Enable size report (default: true)
117
```
118
119
#### Workspace Options
120
121
```bash
122
# Workspace and filtering
123
-W, --workspace [dir] # Enable workspace mode
124
-F, --filter <pattern> # Filter workspace packages (regex or substring)
125
```
126
127
#### Advanced Options
128
129
```bash
130
# Experimental features
131
--exports # Generate export metadata for package.json
132
--copy <dir> # Copy files to output directory
133
--public-dir <dir> # Alias for --copy (deprecated)
134
135
# Logging
136
-l, --logLevel <level> # Set log level: info, warn, error, silent
137
--fail-on-warn # Fail on warnings (default: true)
138
```
139
140
**Complete Example:**
141
142
```bash
143
tsdown src/index.ts \
144
--format esm,cjs \
145
--target node18 \
146
--dts \
147
--sourcemap \
148
--clean \
149
--minify \
150
--external react,react-dom \
151
--env.NODE_ENV=production \
152
--publint \
153
--attw \
154
--watch
155
```
156
157
### Migration Command
158
159
Migration utility for converting tsup configurations to tsdown.
160
161
```bash
162
tsdown migrate [options]
163
```
164
165
```typescript { .api }
166
/**
167
* Migrate from tsup to tsdown configuration
168
* @param options - Migration options
169
*/
170
function migrate(options: {
171
cwd?: string;
172
dryRun?: boolean;
173
}): Promise<void>;
174
```
175
176
**Migration Options:**
177
178
```bash
179
-c, --cwd <dir> # Working directory (default: current directory)
180
-d, --dry-run # Preview changes without applying them
181
```
182
183
**Usage Examples:**
184
185
```bash
186
# Preview migration changes
187
tsdown migrate --dry-run
188
189
# Apply migration in current directory
190
tsdown migrate
191
192
# Migrate project in specific directory
193
tsdown migrate --cwd ./packages/my-lib
194
```
195
196
**Migration Process:**
197
198
1. **package.json Updates**:
199
- Updates `tsup` dependency to `tsdown`
200
- Replaces `tsup` commands in scripts with `tsdown`
201
- Renames `tsup` configuration field to `tsdown`
202
203
2. **Configuration File Migration**:
204
- Converts `tsup.config.*` files to `tsdown.config.*`
205
- Updates import statements and references
206
- Preserves all existing configuration options
207
208
3. **Supported File Extensions**:
209
- `.ts`, `.cts`, `.mts`
210
- `.js`, `.cjs`, `.mjs`
211
- `.json`
212
213
### Debug System
214
215
Comprehensive debugging system with namespaced debug output.
216
217
```bash
218
# Enable all debug output
219
tsdown --debug
220
221
# Enable specific debug namespaces
222
tsdown --debug options,external
223
224
# Debug specific features
225
tsdown --debug rolldown,plugins
226
```
227
228
**Available Debug Namespaces:**
229
- `tsdown:options` - Options resolution and validation
230
- `tsdown:external` - External dependency handling
231
- `tsdown:report` - Size reporting and analysis
232
- `tsdown:rolldown` - Rolldown integration
233
- `tsdown:plugins` - Plugin system operations
234
- `tsdown:workspace` - Workspace discovery and processing
235
236
### Environment Variables
237
238
Environment variables that affect CLI behavior.
239
240
```bash
241
# Debug output
242
DEBUG=tsdown:* # Enable all debug output
243
DEBUG=tsdown:options,external # Enable specific namespaces
244
245
# Node.js optimizations
246
NODE_OPTIONS=--enable-source-maps # Enable source map support
247
```
248
249
### Exit Codes
250
251
The CLI uses standard exit codes for process management:
252
253
- `0` - Success
254
- `1` - Build failure, configuration error, or user cancellation
255
- Process terminates immediately on unhandled errors
256
257
### Output Format
258
259
The CLI provides structured, colorized output with progress indicators:
260
261
```
262
tsdown v0.14.2 powered by rolldown v0.x.x
263
✓ my-package Build complete in 1234ms
264
dist/index.mjs 2.1 kB │ gzip: 1.1 kB
265
dist/index.d.mts 856 B │ gzip: 445 B
266
2 files, total: 2.9 kB
267
```
268
269
### Configuration File Discovery
270
271
The CLI automatically discovers configuration files in the following order:
272
273
1. File specified by `--config` flag
274
2. `tsdown.config.ts`
275
3. `tsdown.config.cts`
276
4. `tsdown.config.mts`
277
5. `tsdown.config.js`
278
6. `tsdown.config.cjs`
279
7. `tsdown.config.mjs`
280
8. `tsdown.config.json`
281
282
### Integration Examples
283
284
**npm scripts integration:**
285
286
```json
287
{
288
"scripts": {
289
"build": "tsdown",
290
"build:watch": "tsdown --watch",
291
"build:prod": "tsdown --minify --clean",
292
"dev": "tsdown --watch --sourcemap",
293
"check": "tsdown --publint --attw --unused"
294
}
295
}
296
```
297
298
**CI/CD integration:**
299
300
```bash
301
# GitHub Actions example
302
- name: Build library
303
run: |
304
npm run build
305
npm run check
306
307
# With specific options for CI
308
- name: Build and validate
309
run: tsdown --format esm,cjs --dts --publint --attw --fail-on-warn
310
```