Skip to content

gentleeduck/duck-ui / .claude/skills/tsdown

tsdown

Verified

Bundle TypeScript and JavaScript libraries with blazing-fast speed powered by Rolldown. Use when building libraries, generating type declarations, bundling for multiple formats, or migrating from tsup.

FileKindSize
LICENSE.mdmarkdown1.1 KB
README.mdmarkdown2.2 KB
SKILL.mdskill md12.6 KB
SYNC.mdmarkdown140 B
agents/openai.yamlconfig98 B
references/README.mdmarkdown4.7 KB
references/advanced-benchmark.mdmarkdown265 B
references/advanced-ci.mdmarkdown2.0 KB
references/advanced-hooks.mdmarkdown6.9 KB
references/advanced-plugins.mdmarkdown6.6 KB
references/advanced-programmatic.mdmarkdown5.9 KB
references/advanced-rolldown-options.mdmarkdown2.3 KB
references/guide-getting-started.mdmarkdown3.1 KB
references/guide-introduction.mdmarkdown1.6 KB
references/guide-migrate-from-tsup.mdmarkdown4.8 KB
references/option-cjs-default.mdmarkdown1.9 KB
references/option-cleaning.mdmarkdown4.8 KB
references/option-config-file.mdmarkdown5.5 KB
references/option-css.mdmarkdown6.9 KB
references/option-dependencies.mdmarkdown7.4 KB
references/option-dts.mdmarkdown4.5 KB
references/option-entry.mdmarkdown3.6 KB
references/option-exe.mdmarkdown3.3 KB
references/option-lint.mdmarkdown2.9 KB
references/option-log-level.mdmarkdown1.8 KB
references/option-minification.mdmarkdown3.5 KB
references/option-output-directory.mdmarkdown4.6 KB
references/option-output-format.mdmarkdown3.6 KB
references/option-package-exports.mdmarkdown5.4 KB
references/option-platform.mdmarkdown5.1 KB
references/option-root.mdmarkdown1.8 KB
references/option-shims.mdmarkdown5.5 KB
references/option-sourcemap.mdmarkdown5.4 KB
references/option-target.mdmarkdown4.0 KB
references/option-tree-shaking.mdmarkdown5.1 KB
references/option-unbundle.mdmarkdown5.5 KB
references/option-watch-mode.mdmarkdown4.6 KB
references/recipe-react.mdmarkdown5.9 KB
references/recipe-solid.mdmarkdown783 B
references/recipe-svelte.mdmarkdown1.4 KB
references/recipe-vue.mdmarkdown6.4 KB
references/recipe-wasm.mdmarkdown2.5 KB
references/reference-cli.mdmarkdown7.3 KB

references/option-output-directory.md

View on GitHub
# Output Directory

Configure the output directory for bundled files.

## Overview

By default, tsdown outputs bundled files to the `dist` directory. You can customize this location using the `outDir` option.

## Basic Usage

### CLI

```bash
# Default output to dist/
tsdown

# Custom output directory
tsdown --out-dir build
tsdown -d lib
```

### Config File

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  outDir: 'build',
})
```

## Common Patterns

### Standard Library

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  outDir: 'dist',  // Default
  dts: true,
})
```

**Output:**
```
dist/
├── index.mjs
├── index.cjs
└── index.d.ts
```

### Separate Directories by Format

```ts
export default defineConfig([
  {
    entry: ['src/index.ts'],
    format: ['esm'],
    outDir: 'dist/esm',
  },
  {
    entry: ['src/index.ts'],
    format: ['cjs'],
    outDir: 'dist/cjs',
  },
])
```

**Output:**
```
dist/
├── esm/
│   └── index.js
└── cjs/
    └── index.js
```

### Monorepo Package

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  outDir: 'lib',  // Custom directory
  clean: true,
})
```

### Build to Root

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  outDir: '.',  // Output to project root (not recommended)
  clean: false,  // Don't clean root!
})
```

**Warning:** Be careful when outputting to root to avoid deleting important files.

## Output Extensions

### Custom Extensions

Use `outExtensions` to control file extensions:

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  outDir: 'dist',
  outExtensions({ format }) {
    return {
      js: format === 'esm' ? '.mjs' : '.cjs',
    }
  },
})
```

### Default Extensions

| Format | Default Extension | With `type: "module"` |
|--------|-------------------|----------------------|
| `esm` | `.mjs` | `.js` |
| `cjs` | `.cjs` | `.js` |
| `iife` | `.iife.js` | `.iife.js` |
| `umd` | `.umd.js` | `.umd.js` |

For IIFE/UMD builds, `outExtensions` customizes extensions or suffixes but does not remove the built-in `.iife` or `.umd` segment. Use `outputOptions.entryFileNames` for custom full filename patterns.

### ESM with .js Extension

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm'],
  outExtensions: () => ({ js: '.js' }),
})
```

Requires `"type": "module"` in package.json.

## File Naming

### Entry Names

Control output filenames based on entry names:

```ts
export default defineConfig({
  entry: {
    index: 'src/index.ts',
    utils: 'src/utils.ts',
  },
  outDir: 'dist',
})
```

**Output:**
```
dist/
├── index.mjs
└── utils.mjs
```

### Glob Entry

```ts
export default defineConfig({
  entry: ['src/**/*.ts', '!**/*.test.ts'],
  outDir: 'dist',
  unbundle: true,  // Preserve structure
})
```

**Output:**
```
dist/
├── index.mjs
├── utils/
│   └── helper.mjs
└── components/
    └── button.mjs
```

## Multiple Builds

### Same Output Directory

```ts
export default defineConfig([
  {
    entry: ['src/index.ts'],
    outDir: 'dist',
    clean: true,  // Clean first
  },
  {
    entry: ['src/cli.ts'],
    outDir: 'dist',
    clean: false,  // Don't clean again
  },
])
```

### Different Output Directories

```ts
export default defineConfig([
  {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    outDir: 'dist/lib',
  },
  {
    entry: ['src/cli.ts'],
    format: ['esm'],
    outDir: 'dist/bin',
  },
])
```

## CLI Examples

```bash
# Default
tsdown

# Custom directory
tsdown --out-dir build
tsdown -d lib

# Nested directory
tsdown --out-dir dist/lib

# With other options
tsdown --out-dir build --format esm,cjs --dts
```

## Tips

1. **Use default `dist`** for standard projects
2. **Be careful with root** - avoid `outDir: '.'`
3. **Clean before build** - use `clean: true`
4. **Consistent naming** - match your project conventions
5. **Separate by format** if needed for clarity
6. **Check .gitignore** - ensure output dir is ignored

## Troubleshooting

### Files Not in Expected Location

- Check `outDir` config
- Verify build completed successfully
- Look for typos in path

### Files Deleted Unexpectedly

- Check if `clean: true`
- Ensure outDir doesn't overlap with source
- Don't use root as outDir

### Permission Errors

- Check write permissions
- Ensure directory isn't locked
- Try different location

## Related Options

- [Cleaning](option-cleaning.md) - Clean output directory
- [Entry](option-entry.md) - Entry points
- [Output Format](option-output-format.md) - Module formats
- [Unbundle](option-unbundle.md) - Preserve structure
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall