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-config-file.md

View on GitHub
# Configuration File

Centralize and manage build settings with a configuration file.

## Overview

tsdown searches for config files automatically in the current directory and parent directories.

## Supported File Names

tsdown looks for these files (in order):
- `tsdown.config.ts`
- `tsdown.config.mts`
- `tsdown.config.cts`
- `tsdown.config.js`
- `tsdown.config.mjs`
- `tsdown.config.cjs`
- `tsdown.config.json`
- `tsdown.config`
- `package.json` (in `tsdown` field)

## Basic Configuration

### TypeScript Config

```ts
// tsdown.config.ts
import { defineConfig } from 'tsdown'

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

### JavaScript Config

```js
// tsdown.config.js
export default {
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
}
```

### JSON Config

```json
// tsdown.config.json
{
  "entry": ["src/index.ts"],
  "format": ["esm", "cjs"],
  "dts": true
}
```

### Package.json Config

```json
// package.json
{
  "name": "my-library",
  "tsdown": {
    "entry": ["src/index.ts"],
    "format": ["esm", "cjs"],
    "dts": true
  }
}
```

## Multiple Configurations

Build multiple outputs with different settings:

```ts
export default defineConfig([
  {
    entry: 'src/index.ts',
    format: ['esm', 'cjs'],
    platform: 'node',
    dts: true,
  },
  {
    entry: 'src/browser.ts',
    format: ['iife'],
    platform: 'browser',
    globalName: 'MyLib',
    minify: true,
  },
])
```

Each configuration runs as a separate build.

## Dynamic Configuration

Use a function for conditional config:

```ts
export default defineConfig((options) => {
  const isDev = options.watch

  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
    clean: !isDev,
  }
})
```

Available options:
- `watch` - Whether watch mode is enabled
- Other CLI flags passed to config

## Config Loaders

Control how TypeScript config files are loaded:

### Auto Loader (Default)

Uses native TypeScript support if available, otherwise falls back to `unrun`:

```bash
tsdown # Uses auto loader
```

### Native Loader

Uses runtime's native TypeScript support (Node.js 22.18.0+, Bun, Deno):

```bash
tsdown --config-loader native
```

### tsx Loader

Uses [tsx](https://tsx.is/) library for loading via its tsImport API. Note: `tsx` is an optional peer dependency — install it manually first.

```bash
pnpm add -D tsx
tsdown --config-loader tsx
```

### Unrun Loader

Uses [unrun](https://gugustinette.github.io/unrun/) library for loading. Note: `unrun` is an optional peer dependency — install it manually first.

```bash
pnpm add -D unrun
tsdown --config-loader unrun
```

**Tip:** Use `tsx` or `unrun` loader if you need to load TypeScript configs without file extensions in Node.js.

## Custom Config Path

Specify a custom config file location:

```bash
tsdown --config ./configs/build.config.ts
# or
tsdown -c custom-config.ts
```

## Disable Config File

Ignore config files and use CLI options only:

```bash
tsdown --no-config src/index.ts --format esm
```

## Extend Vite/Vitest Config (Experimental)

Reuse existing Vite or Vitest configurations:

```bash
# Extend vite.config.*
tsdown --from-vite

# Extend vitest.config.*
tsdown --from-vite vitest
```

**Note:** Only specific options like `resolve` and `plugins` are reused. Test thoroughly as this feature is experimental.

## Workspace / Monorepo

Build multiple packages with a single config:

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

Each package directory matching the glob pattern will be built with the same configuration.

## Common Patterns

### Library with Multiple Builds

```ts
export default defineConfig([
  // Node.js build
  {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    platform: 'node',
    dts: true,
  },
  // Browser build
  {
    entry: ['src/browser.ts'],
    format: ['iife'],
    platform: 'browser',
    globalName: 'MyLib',
  },
])
```

### Development vs Production

```ts
export default defineConfig((options) => ({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  minify: !options.watch,
  sourcemap: options.watch ? true : false,
  clean: !options.watch,
}))
```

### Monorepo Root Config

```ts
// Root tsdown.config.ts
export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
  // Shared config for all packages
})
```

### Per-Package Override

```ts
// packages/special/tsdown.config.ts
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm'], // Override: only ESM
  platform: 'browser', // Override: browser only
})
```

## Config Precedence

When multiple configs exist:

1. CLI options (highest priority)
2. Config file specified with `--config`
3. Auto-discovered config files
4. Package.json `tsdown` field
5. Default values

## Tips

1. **Use TypeScript config** for type checking and autocomplete
2. **Use defineConfig** helper for better DX
3. **Export arrays** for multiple build configurations
4. **Use functions** for dynamic/conditional configs
5. **Keep configs simple** - prefer convention over configuration
6. **Use workspace** for monorepo builds
7. **Test experimental features** thoroughly before production use

## Related Options

- [Entry](option-entry.md) - Configure entry points
- [Output Format](option-output-format.md) - Output formats
- [Watch Mode](option-watch-mode.md) - Watch mode configuration
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