agent-skills/skills/tsdown/references/option-watch-mode.md

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

# 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

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

Watch Options

Ignore Paths

Ignore specific paths in watch mode:

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

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

On Success Command

Run command after successful build:

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

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

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

With Post-Build Script

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

Multiple Entry Points

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

# 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

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

Advanced Configuration

Custom Watch Options

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

Conditional Watch

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

# 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:

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 - Post-build commands
• Sourcemap - Debug information
• Clean - Output directory cleaning