gentleeduck/duck-ui / .claude/skills/tsdown
tsdown
VerifiedBundle 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.
references/option-dts.md
View on GitHub# TypeScript Declaration Files
Generate `.d.ts` type declaration files for your library.
## Overview
tsdown uses [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts) to generate and bundle TypeScript declaration files.
**Requirements:**
- TypeScript must be installed in your project
## Enabling DTS Generation
### Auto-Enabled
DTS generation is **automatically enabled** if `package.json` contains:
- `types` field, or
- `typings` field
### Manual Enable
#### CLI
```bash
tsdown --dts
```
#### Config File
```ts
export default defineConfig({
dts: true,
})
```
## Performance
### With `isolatedDeclarations` (Recommended)
**Extremely fast** - uses oxc-transform for generation.
```json
// tsconfig.json
{
"compilerOptions": {
"isolatedDeclarations": true
}
}
```
### Without `isolatedDeclarations`
Falls back to TypeScript compiler. Reliable but slower.
## Declaration Maps
Map `.d.ts` files back to original `.ts` sources (useful for monorepos).
### Enable in tsconfig.json
```json
{
"compilerOptions": {
"declarationMap": true
}
}
```
### Enable in tsdown Config
```ts
export default defineConfig({
dts: {
sourcemap: true,
},
})
```
## Advanced Options
### Custom Compiler Options
Override TypeScript compiler options:
```ts
export default defineConfig({
dts: {
compilerOptions: {
removeComments: false,
},
},
})
```
## Build Process
- **ESM format**: `.js` and `.d.ts` files generated in same build
- **CJS format**: Separate build process for `.d.ts` files
## Common Patterns
### Basic Library
```ts
export default defineConfig({
entry: ['src/index.ts'],
format: ['esm', 'cjs'],
dts: true,
})
```
Output:
- `dist/index.mjs`
- `dist/index.cjs`
- `dist/index.d.ts`
### Multiple Entry Points
```ts
export default defineConfig({
entry: {
index: 'src/index.ts',
utils: 'src/utils.ts',
},
format: ['esm', 'cjs'],
dts: true,
})
```
Output:
- `dist/index.mjs`, `dist/index.cjs`, `dist/index.d.ts`
- `dist/utils.mjs`, `dist/utils.cjs`, `dist/utils.d.ts`
### With Monorepo Support
```ts
export default defineConfig({
entry: ['src/index.ts'],
format: ['esm', 'cjs'],
dts: {
sourcemap: true, // Enable declaration maps
},
})
```
### Fast Build (Isolated Declarations)
```json
// tsconfig.json
{
"compilerOptions": {
"isolatedDeclarations": true,
"declaration": true,
"declarationMap": true
}
}
```
```ts
// tsdown.config.ts
export default defineConfig({
entry: ['src/index.ts'],
format: ['esm', 'cjs'],
dts: true, // Will use fast oxc-transform
})
```
## Troubleshooting
### Missing Types
Ensure TypeScript is installed:
```bash
pnpm add -D typescript
```
### Slow Generation
Enable `isolatedDeclarations` in `tsconfig.json` for faster builds.
### Declaration Errors
Check that all exports have explicit types (required for `isolatedDeclarations`).
### Report Issues
For DTS-specific issues, report to [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts/issues).
### Vue Support
Enable Vue component type generation (requires `vue-tsc`):
```ts
export default defineConfig({
dts: {
vue: true,
},
})
```
### Oxc Transform
Control Oxc usage for declaration generation:
```ts
export default defineConfig({
dts: {
oxc: true, // Use oxc-transform (fast, requires isolatedDeclarations)
},
})
```
### Custom TSConfig
Specify a different tsconfig for DTS generation:
```ts
export default defineConfig({
dts: {
tsconfig: './tsconfig.build.json',
},
})
```
## Available DTS Options
| Option | Type | Description |
|--------|------|-------------|
| `sourcemap` | `boolean` | Generate declaration source maps |
| `compilerOptions` | `object` | Override TypeScript compiler options |
| `vue` | `boolean` | Enable Vue type generation (requires vue-tsc) |
| `oxc` | `boolean` | Use oxc-transform for fast generation |
| `tsconfig` | `string` | Path to tsconfig file |
| `resolver` | `'oxc' \| 'tsc'` | Module resolver: `'oxc'` (default, fast) or `'tsc'` (more compatible) |
| `cjsDefault` | `boolean` | CJS default export handling |
| `sideEffects` | `boolean` | Preserve side effects in declarations |
## Tips
1. **Always enable DTS** for TypeScript libraries
2. **Use isolatedDeclarations** for fast builds
3. **Enable declaration maps** in monorepos
4. **Ensure explicit types** for all exports
5. **Install TypeScript** as dev dependency
## Related Options
- [Entry](option-entry.md) - Configure entry points
- [Output Format](option-output-format.md) - Multiple output formats
- [Target](option-target.md) - JavaScript version
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |