# Migrating a Node.js CLI from tsup to tsdown

A step-by-step guide for migrating a TypeScript Node.js CLI project from
[tsup](https://tsup.egoist.dev/) to [tsdown](https://tsdown.dev/). Based on a
real migration and cross-referenced with the
[official tsdown migration guide](https://tsdown.dev/guide/migrate-from-tsup)
and the
[Turborepo tsup-to-tsdown PR](https://github.com/vercel/turborepo/pull/11649).

## Prerequisites

- Node.js >= 20.19 (required by tsdown)
- pnpm (guide uses pnpm commands; adapt for npm/yarn as needed)
- Existing tsup-based project with a `tsup.config.ts` and dual ESM/CJS output

## Overview of changes

| File | Action |
| --- | --- |
| `package.json` | Swap `tsup` for `tsdown` in devDependencies, update build script |
| `tsup.config.ts` | Delete |
| `tsdown.config.ts` | Create with equivalent config |
| `package.json` exports/types | Update `.d.ts` references to `.d.mts` / `.d.cts` |
| `pnpm-workspace.yaml` | Allow native build scripts for rolldown dependencies |
| ESLint config | Ensure `dist/` is excluded from linting |

---

## Step 1: Swap the dependency and build script

In `package.json`:

1. Remove `tsup` from `devDependencies`.
2. Add `tsdown` to `devDependencies`.
3. Update the `build` script to call `tsdown` instead of `tsup`.

```diff
 "scripts": {
-  "build": "tsc && tsup",
+  "build": "tsc && tsdown",
 },
 "devDependencies": {
-  "tsup": "^8.1.0",
+  "tsdown": "^0.9.0",
 }
```

## Step 2: Replace the config file

Delete `tsup.config.ts` and create `tsdown.config.ts`. The config uses
`defineConfig` imported from `tsdown` instead of `tsup`.

### Option mapping reference

Use this table to translate your tsup config options into tsdown equivalents:

| tsup option | tsdown equivalent | Notes |
| --- | --- | --- |
| `entryPoints` | `entry` | Different key name, same purpose |
| `format: ['cjs', 'esm']` | `format: ['cjs', 'esm']` | Identical syntax. tsdown defaults to `esm` only, so always set this explicitly for dual output |
| `dts: true` | `dts: true` | Auto-detected if `package.json` has a `types` field, but explicit is fine |
| `outDir` | `outDir` | Identical |
| `clean: true` | `clean: true` | Enabled by default in tsdown |
| `sourcemap: false` | `sourcemap: false` | Disabled by default in tsdown. Note: if your `tsconfig.json` has `declarationMap: true`, tsdown will force sourcemaps on for declaration files regardless of this setting |
| `bundle: true` | _(default)_ | tsdown bundles by default; use `unbundle: true` to mirror input structure |
| `splitting: false` | _(N/A)_ | tsdown does not have a `splitting` option; single-entry chunks do not split by default |
| `outExtension` | `outExtensions` | Note the plural "s". Different function signature (see below). Often unnecessary when using `fixedExtension: true` |
| `treeshake: false` | `treeshake: false` | tsdown defaults to `true`, so set explicitly if you want it off |
| `target` | `target` | Identical. tsdown also auto-reads from `engines.node` in `package.json` if not set |
| `platform: 'node'` | `platform: 'node'` | Identical |
| `tsconfig` | `tsconfig` | Identical |
| `cjsInterop: true` | `cjsDefault: true` | tsdown's equivalent for CJS default export interop |
| `keepNames: true` | _(N/A)_ | No direct equivalent in tsdown; drop this option |
| `skipNodeModulesBundle` | _(default)_ | tsdown handles externals via the `deps` config; default behavior is equivalent |
| `minify: false` | `minify: false` | Disabled by default in tsdown |

### The `fixedExtension` option

When `platform` is set to `'node'`, tsdown defaults `fixedExtension` to `true`.
This means output files always use `.cjs` / `.mjs` extensions (and `.d.cts` /
`.d.mts` for declarations) regardless of the package `type` field. This
typically makes a custom `outExtensions` function unnecessary.

If you previously had a tsup `outExtension` function like:

```typescript
outExtension(ctx) {
  return {
    dts: '.d.ts',
    js: ctx.format === 'cjs' ? '.cjs' : '.mjs',
  }
}
```

You can replace it with just `fixedExtension: true` in tsdown (or omit it
entirely for `platform: 'node'` since it's the default).

### Example config

**Before** (`tsup.config.ts`):

```typescript
import { defineConfig } from 'tsup'

export default defineConfig([
  {
    entryPoints: ['src/main.ts', 'src/bin/cli.ts'],
    format: ['cjs', 'esm'],
    dts: true,
    minify: false,
    outDir: 'dist/',
    clean: true,
    sourcemap: false,
    bundle: true,
    splitting: false,
    outExtension(ctx) {
      return {
        dts: '.d.ts',
        js: ctx.format === 'cjs' ? '.cjs' : '.mjs',
      }
    },
    treeshake: false,
    target: 'es2022',
    platform: 'node',
    tsconfig: './tsconfig.json',
    cjsInterop: true,
    keepNames: true,
    skipNodeModulesBundle: false,
  },
])
```

**After** (`tsdown.config.ts`):

```typescript
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['src/main.ts', 'src/bin/cli.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  outDir: 'dist/',
  clean: true,
  sourcemap: false,
  treeshake: false,
  target: 'es2022',
  platform: 'node',
  tsconfig: './tsconfig.json',
  cjsDefault: true,
  fixedExtension: true,
  minify: false,
})
```

Key differences:

- No array wrapper needed (single config object, not `defineConfig([...])`)
- `entryPoints` becomes `entry`
- `cjsInterop` becomes `cjsDefault`
- `bundle`, `splitting`, `keepNames`, `skipNodeModulesBundle` are dropped
- `outExtension` function replaced by `fixedExtension: true`

### CommonJS packages

If your package has `"type": "commonjs"` in `package.json`, name the config file
`tsdown.config.mts` instead of `tsdown.config.ts` (as noted in the
[Turborepo migration PR](https://github.com/vercel/turborepo/pull/11649)).

## Step 3: Update declaration file references in package.json

tsdown with `fixedExtension: true` produces `.d.mts` for ESM declarations and
`.d.cts` for CJS declarations. tsup typically produced `.d.ts` for ESM. You need
to update any references in `package.json`:

```diff
-"types": "dist/main.d.ts",
+"types": "dist/main.d.mts",
```

```diff
 "exports": {
   ".": {
     "import": {
-      "types": "./dist/main.d.ts",
+      "types": "./dist/main.d.mts",
       "default": "./dist/main.mjs"
     },
     "require": {
       "types": "./dist/main.d.cts",
       "default": "./dist/main.cjs"
     }
   }
 }
```

The `bin` field pointing to `.cjs` files does not need to change -- tsdown
produces `.cjs` files with the shebang (`#!/usr/bin/env node`) intact and
automatically grants execute permission.

## Step 4: Allow native build scripts (pnpm)

tsdown depends on [rolldown](https://rolldown.rs/) (Rust-based bundler) and
other native packages that need to run postinstall scripts. If your
`pnpm-workspace.yaml` uses `onlyBuiltDependencies` or you have strict install
policies, add these packages:

```yaml
onlyBuiltDependencies:
  - esbuild
  - rolldown
  - unrs-resolver
```

Without this, `pnpm install` will skip the native binary downloads and tsdown
will fail at runtime.

## Step 5: Ensure dist/ is excluded from ESLint

tsdown's output code style differs from tsup's (tabs vs spaces, semicolons,
variable naming, etc.). If your ESLint config lints `dist/` files, you will get
false lint failures. Make sure `dist/**` is in your ESLint ignores:

```javascript
// eslint.config.js (flat config)
export default [
  {
    ignores: ['dist/**'],
  },
  // ... rest of config
]
```

Or for legacy `.eslintrc`:

```json
{
  "ignorePatterns": ["dist/**"]
}
```

This is good practice regardless of bundler -- build output should never be
linted.

## Step 6: Install and verify

```bash
# Update the lockfile and install tsdown
pnpm install --no-frozen-lockfile

# Run the build
pnpm run build

# Verify output files exist
ls dist/

# Expected output structure for a dual ESM/CJS CLI:
# dist/main.mjs          (ESM entry)
# dist/main.cjs          (CJS entry)
# dist/main.d.mts        (ESM declarations)
# dist/main.d.cts        (CJS declarations)
# dist/bin/cli.mjs       (ESM CLI)
# dist/bin/cli.cjs       (CJS CLI, with shebang)

# Test the CLI binary
node dist/bin/cli.cjs

# Run lint
pnpm run lint

# Run tests
pnpm run test
```

## Behavioral differences to be aware of

### Declaration file extensions

tsdown uses `.d.mts` / `.d.cts` with `fixedExtension: true`, whereas tsup
typically used `.d.ts` / `.d.cts`. Update all `types` references in
`package.json` accordingly.

### Declaration maps

If your `tsconfig.json` has `declarationMap: true`, tsdown will generate
`.d.mts.map` and `.d.cts.map` files and will force sourcemaps on for the
declaration build, regardless of the `sourcemap` setting in `tsdown.config.ts`.

### Chunk naming

tsdown may produce internal chunks with hashed filenames (e.g.,
`main-DM5FYoS9.cjs`). These are implementation details invisible to package
consumers -- the public entry points (`main.cjs`, `main.mjs`) re-export from
them.

### Target auto-detection

If you omit `target`, tsdown reads from `engines.node` in `package.json`. For
example, `"node": ">=24.0.0"` would auto-set the target to `node24`. Set
`target` explicitly if you want a specific ES version like `es2022`.

### Shebang and execute permissions

tsdown automatically detects CLI entry points, preserves the `#!/usr/bin/env
node` shebang, and grants execute permission to the output file. No special
configuration needed.

### No `keepNames` equivalent

tsdown does not have a `keepNames` option (which preserves `Function.name` and
`Class.name`). If your code relies on `Function.name` at runtime, verify that
the bundled output still works correctly.

## Quick checklist

- [ ] Replace `tsup` with `tsdown` in `devDependencies`
- [ ] Update build script from `tsup` to `tsdown`
- [ ] Delete `tsup.config.ts`
- [ ] Create `tsdown.config.ts` (or `.mts` for CJS packages) with mapped options
- [ ] Update `types` and `exports.*.types` in `package.json` (`.d.ts` to `.d.mts`)
- [ ] Allow native build scripts in pnpm (`onlyBuiltDependencies`)
- [ ] Ensure `dist/` is excluded from ESLint
- [ ] Run `pnpm install --no-frozen-lockfile`
- [ ] Run `pnpm run build` and verify output files
- [ ] Run `pnpm run lint` and confirm no regressions
- [ ] Run `pnpm run test` and confirm all tests pass
- [ ] Test the CLI binary manually (`node dist/bin/cli.cjs`)

## References

- [tsdown documentation](https://tsdown.dev/guide/)
- [tsdown UserConfig API reference](https://tsdown.dev/reference/api/Interface.UserConfig)
- [tsdown migration guide from tsup](https://tsdown.dev/guide/migrate-from-tsup)
- [Turborepo tsup-to-tsdown PR #11649](https://github.com/vercel/turborepo/pull/11649)