agent-skills/skills/tsdown/references/option-output-directory.md

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

# Default output to dist/
tsdown

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

Config File

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

Common Patterns

Standard Library

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

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

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

Build to Root

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:

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	.global.js	.global.js
umd	.umd.js	.umd.js

ESM with .js Extension

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:

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

Output:

dist/
├── index.mjs
└── utils.mjs

Glob Entry

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

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

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

CLI Examples

# 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 - Clean output directory
• Entry - Entry points
• Output Format - Module formats
• Unbundle - Preserve structure