0
# Migration Tools
1

2
Built-in migration utilities for moving from tsup to tsdown with automatic configuration conversion. Provides seamless migration path with dry-run capabilities and comprehensive file updates.
3

4
## Capabilities
5

6
### Migration Function
7

8
Main migration function that converts tsup configurations and dependencies to tsdown equivalents.
9

10
```typescript { .api }
11
/**
12
 * Migrate from tsup to tsdown configuration and dependencies
13
 * @internal Not exported from main entry point - use CLI instead
14
 * @param options - Migration configuration options
15
 */
16
function migrate(options: {
17
  cwd?: string;
18
  dryRun?: boolean;
19
}): Promise<void>;
20
```
21

22
**Usage Examples:**
23

24
```typescript
25
// Note: migrate function is only available via CLI
26
// For programmatic usage, it's an internal function
27
// Use CLI: npx tsdown migrate
28

29
// If needed programmatically (not part of public API):
30
// import { migrate } from "tsdown/src/migrate";
31
```
32

33
### Migration Process
34

35
The migration process handles multiple aspects of converting from tsup to tsdown:
36

37
#### 1. Package.json Updates
38

39
**Dependency Fields Updated:**
40
- `dependencies` - Updates `tsup` to `tsdown` with current version
41
- `devDependencies` - Updates `tsup` to `tsdown` with current version  
42
- `peerDependencies` - Updates `tsup` to `tsdown` with wildcard version
43

44
**Script Updates:**
45
- Replaces `tsup` commands with `tsdown` in all scripts
46
- Handles `tsup-node` commands (also converted to `tsdown`)
47
- Preserves all command-line arguments and options
48

49
**Configuration Field Updates:**
50
- Renames `tsup` configuration field to `tsdown` in package.json
51

52
**Example Migration:**
53

54
```json
55
// Before migration
56
{
57
  "devDependencies": {
58
    "tsup": "^8.0.0"
59
  },
60
  "scripts": {
61
    "build": "tsup src/index.ts",
62
    "dev": "tsup src/index.ts --watch",
63
    "build:prod": "tsup-node --minify"
64
  },
65
  "tsup": {
66
    "entry": "src/index.ts",
67
    "format": ["esm", "cjs"]
68
  }
69
}
70

71
// After migration
72
{
73
  "devDependencies": {
74
    "tsdown": "^0.14.2"
75
  },
76
  "scripts": {
77
    "build": "tsdown src/index.ts",
78
    "dev": "tsdown src/index.ts --watch", 
79
    "build:prod": "tsdown --minify"
80
  },
81
  "tsdown": {
82
    "entry": "src/index.ts",
83
    "format": ["esm", "cjs"]
84
  }
85
}
86
```
87

88
#### 2. Configuration File Migration
89

90
**Supported Configuration Files:**
91
- `tsup.config.ts` → `tsdown.config.ts`
92
- `tsup.config.cts` → `tsdown.config.cts`
93
- `tsup.config.mts` → `tsdown.config.mts`
94
- `tsup.config.js` → `tsdown.config.js`
95
- `tsup.config.cjs` → `tsdown.config.cjs`
96
- `tsup.config.mjs` → `tsdown.config.mjs`
97
- `tsup.config.json` → `tsdown.config.json`
98

99
**Content Updates:**
100
- Replaces all instances of `tsup` with `tsdown` in code
101
- Replaces all instances of `TSUP` with `TSDOWN` in constants
102
- Updates import statements and references
103
- Preserves all existing configuration options and structure
104

105
**Example Configuration Migration:**
106

107
```typescript
108
// Before: tsup.config.ts
109
import { defineConfig } from 'tsup';
110

111
export default defineConfig({
112
  entry: 'src/index.ts',
113
  format: ['esm', 'cjs'],
114
  dts: true,
115
  onSuccess: 'echo "TSUP build complete"'
116
});
117

118
// After: tsdown.config.ts  
119
import { defineConfig } from 'tsdown';
120

121
export default defineConfig({
122
  entry: 'src/index.ts',
123
  format: ['esm', 'cjs'],
124
  dts: true,
125
  onSuccess: 'echo "TSDOWN build complete"'
126
});
127
```
128

129
### Dry Run Mode
130

131
Preview migration changes without applying them to files.
132

133
```typescript { .api }
134
interface MigrateOptions {
135
  /**
136
   * Preview changes without applying them
137
   * @default false
138
   */
139
  dryRun?: boolean;
140
}
141
```
142

143
**Dry Run Output:**
144
- Shows unified diff of all file changes
145
- Displays package.json modifications
146
- Shows configuration file renames and content changes
147
- No files are actually modified
148

149
**Example Dry Run:**
150

151
```bash
152
tsdown migrate --dry-run
153

154
# Output:
155
[dry-run] package.json:
156
--- package.json
157
+++ package.json
158
@@ -2,7 +2,7 @@
159
   "name": "my-library",
160
   "devDependencies": {
161
-    "tsup": "^8.0.0"
162
+    "tsdown": "^0.14.2"
163
   },
164
   "scripts": {
165
-    "build": "tsup src/index.ts"
166
+    "build": "tsdown src/index.ts"
167
   }
168

169
[dry-run] tsup.config.ts -> tsdown.config.ts:
170
--- tsup.config.ts
171
+++ tsdown.config.ts
172
@@ -1,4 +1,4 @@
173
-import { defineConfig } from 'tsup';
174
+import { defineConfig } from 'tsdown';
175
```
176

177
### CLI Migration Command
178

179
Command-line interface for migration operations.
180

181
```bash
182
tsdown migrate [options]
183
```
184

185
**Options:**
186
- `-c, --cwd <dir>` - Working directory (default: current directory)
187
- `-d, --dry-run` - Preview changes without applying them
188

189
**Interactive Confirmation:**
190
The migration command includes safety prompts to prevent accidental changes:
191

192
```bash
193
tsdown migrate
194

195
# Output:
196
Before proceeding, review the migration guide at https://tsdown.dev/guide/migrate-from-tsup, 
197
as this process will modify your files.
198
Uncommitted changes will be lost. Use the --dry-run flag to preview changes without applying them.
199

200
Continue? (Y/n)
201
```
202

203
### Migration Validation
204

205
The migration process validates and reports on the success of operations:
206

207
#### Success Cases
208
- Dependencies found and updated successfully
209
- Scripts containing tsup commands updated
210
- Configuration files found and migrated
211
- All changes applied without errors
212

213
#### Error Cases
214
- No `package.json` found in target directory
215
- No tsup-related content found to migrate
216
- File system permission errors
217
- Invalid JSON in configuration files
218

219
#### Example Success Output
220

221
```bash
222
tsdown migrate
223

224
✓ Migrating `devDependencies` to tsdown.
225
✓ Migrating `build` script to tsdown
226
✓ Migrating `dev` script to tsdown  
227
✓ Found `tsup.config.ts`
228
✓ Migrated `tsup.config.ts` to `tsdown.config.ts`
229
✓ Migration completed. Remember to run install command with your package manager.
230
```
231

232
### Post-Migration Steps
233

234
After successful migration, users should:
235

236
1. **Install Dependencies**: Run package manager install command
237
   ```bash
238
   npm install
239
   # or
240
   yarn install
241
   # or  
242
   pnpm install
243
   ```
244

245
2. **Verify Configuration**: Test that existing build configurations work
246
   ```bash
247
   npm run build
248
   ```
249

250
3. **Update Documentation**: Update any documentation referencing tsup
251
4. **Commit Changes**: Commit the migration changes to version control
252

253
### Configuration Compatibility
254

255
tsdown maintains high compatibility with tsup configuration options:
256

257
- **Supported Options**: All major tsup options are supported in tsdown
258
- **New Options**: tsdown-specific options can be added after migration
259
- **Deprecated Options**: Warnings are shown for deprecated options with migration paths
260

261
### Workspace Migration
262

263
Migration works seamlessly with workspace/monorepo setups:
264

265
```bash
266
# Migrate root configuration
267
tsdown migrate
268

269
# Migrate individual packages
270
tsdown migrate --cwd packages/ui-lib
271
tsdown migrate --cwd packages/utils
272

273
# Or migrate all packages with a script
274
for dir in packages/*/; do
275
  tsdown migrate --cwd "$dir"
276
done
277
```
278

279
### Troubleshooting Migration
280

281
Common migration issues and solutions:
282

283
- **Permission Errors**: Ensure write permissions on all files
284
- **No Changes Found**: Verify tsup is actually in use in the project
285
- **Invalid JSON**: Fix malformed package.json before migration
286
- **Git Conflicts**: Commit or stash changes before migration
287
- **Missing Dependencies**: Run package manager install after migration