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-watch-mode.md

View on GitHub
# Watch Mode

Automatically rebuild when files change.

## Overview

Watch mode monitors your source files and rebuilds automatically on changes, streamlining the development workflow.

## Basic Usage

### CLI

```bash
# Watch all project files
tsdown --watch

# Or use short flag
tsdown -w

# Watch specific directory
tsdown --watch ./src

# Watch specific file
tsdown --watch ./src/index.ts
```

### Config File

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

## Watch Options

### Ignore Paths

Ignore specific paths in watch mode:

```bash
tsdown --watch --ignore-watch test --ignore-watch '**/*.test.ts'
```

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  watch: {
    exclude: ['test/**', '**/*.test.ts'],
  },
})
```

### On Success Command

Run command after successful build:

```bash
tsdown --watch --on-success "echo Build complete!"
tsdown --watch --on-success "node dist/index.mjs"
```

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  watch: true,
  onSuccess: 'node dist/index.mjs',
})
```

## Watch Behavior

### Default Watch Targets

By default, tsdown watches:
- All entry files
- All imported files
- Config file (triggers restart)

### File Change Handling

- **Source files** - Incremental rebuild
- **Config file** - Full restart with cache clear
- **Dependencies** - Rebuild if imported

### Keyboard Shortcuts

During watch mode:
- `r` - Manual rebuild
- `q` - Quit watch mode

## Common Patterns

### Development Mode

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

### With Post-Build Script

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  watch: true,
  onSuccess: 'npm run test',
})
```

### Multiple Entry Points

```ts
export default defineConfig({
  entry: {
    main: 'src/index.ts',
    cli: 'src/cli.ts',
  },
  watch: true,
  clean: false,  // Don't clean on each rebuild
})
```

### Test Runner Integration

```bash
# Watch and run tests on change
tsdown --watch --on-success "vitest run"

# Watch and start dev server
tsdown --watch --on-success "node dist/server.mjs"
```

### Monorepo Package

```ts
export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  watch: true,
  watch: {
    exclude: ['**/test/**', '**/*.spec.ts'],
  },
})
```

## Advanced Configuration

### Custom Watch Options

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  watch: {
    include: ['src/**'],
    exclude: ['**/*.test.ts', '**/fixtures/**'],
    skipWrite: false,
  },
})
```

### Conditional Watch

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

  return {
    entry: ['src/index.ts'],
    format: ['esm'],
    dts: !isDev,        // Skip DTS in watch mode
    sourcemap: isDev,
    clean: !isDev,
  }
})
```

## CLI Examples

```bash
# Basic watch
tsdown -w

# Watch with source maps
tsdown -w --sourcemap

# Watch without cleaning
tsdown -w --no-clean

# Watch and run on success
tsdown -w --on-success "npm test"

# Watch specific format
tsdown -w --format esm

# Watch with minification
tsdown -w --minify

# Watch and ignore test files
tsdown -w --ignore-watch '**/*.test.ts'
```

## Tips

1. **Use watch mode** for active development
2. **Skip DTS generation** in watch for faster rebuilds
3. **Disable clean** to avoid unnecessary file operations
4. **Use onSuccess** for post-build tasks
5. **Ignore test files** to avoid unnecessary rebuilds
6. **Use keyboard shortcuts** for manual control

## Troubleshooting

### Watch Not Detecting Changes

- Check file is in entry or imported chain
- Verify path is not in `exclude` patterns
- Ensure file system supports watching

### Too Many Rebuilds

Add ignore patterns:

```ts
export default defineConfig({
  watch: {
    exclude: [
      '**/node_modules/**',
      '**/.git/**',
      '**/dist/**',
      '**/*.test.ts',
    ],
  },
})
```

### Slow Rebuilds

- Skip DTS in watch mode: `dts: !options.watch`
- Disable minification: `minify: false`
- Use smaller entry set during development

### Config Changes Not Applied

Config file changes trigger full restart automatically.

### Why Not Stub Mode?

tsdown does not support stub mode. Watch mode is the recommended alternative for rapid development, providing instant rebuilds without the drawbacks of stub mode.

## Related Options

- [On Success](reference-cli.md#on-success-command) - Post-build commands
- [Sourcemap](option-sourcemap.md) - Debug information
- [Clean](option-cleaning.md) - Output directory cleaning
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