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/advanced-hooks.md

View on GitHub
# Lifecycle Hooks

Extend the build process with lifecycle hooks.

## Overview

Hooks provide a way to inject custom logic at specific stages of the build lifecycle. Inspired by [unbuild](https://github.com/unjs/unbuild).

**Recommendation:** Use [plugins](advanced-plugins.md) for most extensions. Use hooks for simple custom tasks or Rolldown plugin injection.

## Usage Patterns

### Object Syntax

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  hooks: {
    'build:prepare': async (context) => {
      console.log('Build starting...')
    },
    'build:done': async (context) => {
      console.log('Build complete!')
    },
  },
})
```

### Function Syntax

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  hooks(hooks) {
    hooks.hook('build:prepare', () => {
      console.log('Preparing build...')
    })

    hooks.hook('build:before', (context) => {
      console.log(`Building format: ${context.format}`)
    })
  },
})
```

## Available Hooks

### `build:prepare`

Called before the build process starts.

**When:** Once per build session

**Context:**
```ts
{
  options: ResolvedConfig,
  hooks: Hookable
}
```

**Use cases:**
- Setup tasks
- Validation
- Environment preparation

**Example:**
```ts
hooks: {
  'build:prepare': async (context) => {
    console.log('Starting build for:', context.options.entry)
    await cleanOldFiles()
  },
}
```

### `build:before`

Called before each Rolldown build.

**When:** Once per format (ESM, CJS, etc.)

**Context:**
```ts
{
  options: ResolvedConfig,
  buildOptions: BuildOptions,
  hooks: Hookable
}
```

**Use cases:**
- Modify build options per format
- Inject plugins dynamically
- Format-specific setup

**Example:**
```ts
hooks: {
  'build:before': async (context) => {
    console.log(`Building ${context.buildOptions.format} format...`)

    // Add format-specific plugin
    if (context.buildOptions.format === 'iife') {
      context.buildOptions.plugins.push(browserPlugin())
    }
  },
}
```

### `build:done`

Called after the build completes.

**When:** Once per build session

**Context:**
```ts
{
  options: ResolvedConfig,
  chunks: RolldownChunk[],
  hooks: Hookable
}
```

**Use cases:**
- Post-processing
- Asset copying
- Notifications
- Deployment

**Example:**
```ts
hooks: {
  'build:done': async (context) => {
    console.log(`Built ${context.chunks.length} chunks`)

    // Copy additional files
    await copyAssets()

    // Send notification
    notifyBuildComplete()
  },
}
```

## Common Patterns

### Build Notifications

```ts
export default defineConfig({
  hooks: {
    'build:prepare': () => {
      console.log('🚀 Starting build...')
    },
    'build:done': (context) => {
      const size = context.chunks.reduce((sum, c) => sum + c.code.length, 0)
      console.log(`✅ Build complete! Total size: ${size} bytes`)
    },
  },
})
```

### Conditional Plugin Injection

```ts
export default defineConfig({
  hooks(hooks) {
    hooks.hook('build:before', (context) => {
      // Add minification only for production
      if (process.env.NODE_ENV === 'production') {
        context.buildOptions.plugins.push(minifyPlugin())
      }
    })
  },
})
```

### Custom File Copy

```ts
import { copyFile } from 'fs/promises'

export default defineConfig({
  hooks: {
    'build:done': async (context) => {
      // Copy README to dist
      await copyFile('README.md', `${context.options.outDir}/README.md`)
    },
  },
})
```

### Build Metrics

```ts
export default defineConfig({
  hooks: {
    'build:prepare': (context) => {
      context.startTime = Date.now()
    },
    'build:done': (context) => {
      const duration = Date.now() - context.startTime
      console.log(`Build took ${duration}ms`)

      // Log chunk sizes
      context.chunks.forEach((chunk) => {
        console.log(`${chunk.fileName}: ${chunk.code.length} bytes`)
      })
    },
  },
})
```

### Format-Specific Logic

```ts
export default defineConfig({
  format: ['esm', 'cjs', 'iife'],
  hooks: {
    'build:before': (context) => {
      const format = context.buildOptions.format

      if (format === 'iife') {
        // Browser-specific setup
        context.buildOptions.globalName = 'MyLib'
      } else if (format === 'cjs') {
        // Node-specific setup
        context.buildOptions.platform = 'node'
      }
    },
  },
})
```

### Deployment Hook

```ts
export default defineConfig({
  hooks: {
    'build:done': async (context) => {
      if (process.env.DEPLOY === 'true') {
        console.log('Deploying to CDN...')
        await deployToCDN(context.options.outDir)
      }
    },
  },
})
```

## Advanced Usage

### Multiple Hooks

```ts
export default defineConfig({
  hooks(hooks) {
    // Register multiple hooks
    hooks.hook('build:prepare', setupEnvironment)
    hooks.hook('build:prepare', validateConfig)

    hooks.hook('build:before', injectPlugins)
    hooks.hook('build:before', logFormat)

    hooks.hook('build:done', generateManifest)
    hooks.hook('build:done', notifyComplete)
  },
})
```

### Async Hooks

```ts
export default defineConfig({
  hooks: {
    'build:prepare': async (context) => {
      await fetchRemoteConfig()
      await initializeDatabase()
    },
    'build:done': async (context) => {
      await uploadToS3(context.chunks)
      await invalidateCDN()
    },
  },
})
```

### Error Handling

```ts
export default defineConfig({
  hooks: {
    'build:done': async (context) => {
      try {
        await riskyOperation()
      } catch (error) {
        console.error('Hook failed:', error)
        // Don't throw - allow build to complete
      }
    },
  },
})
```

## Hookable API

tsdown uses [hookable](https://github.com/unjs/hookable) for hooks. Additional methods:

```ts
export default defineConfig({
  hooks(hooks) {
    // Register hook
    hooks.hook('build:done', handler)

    // Register hook once
    hooks.hookOnce('build:prepare', handler)

    // Remove hook
    hooks.removeHook('build:done', handler)

    // Clear all hooks for event
    hooks.removeHooks('build:done')

    // Call hooks manually
    await hooks.callHook('build:done', context)
  },
})
```

## Tips

1. **Use plugins** for most extensions
2. **Hooks for simple tasks** like notifications or file copying
3. **Async hooks supported** for I/O operations
4. **Don't throw errors** unless you want to fail the build
5. **Context is mutable** in `build:before` for advanced use cases
6. **Multiple hooks allowed** for the same event

## Troubleshooting

### Hook Not Called

- Verify hook name is correct
- Check hook is registered in config
- Ensure async hooks are awaited

### Build Fails in Hook

- Add try/catch for error handling
- Don't throw unless intentional
- Log errors for debugging

### Context Undefined

- Check which hook you're using
- Verify context properties available for that hook

## Related

- [Plugins](advanced-plugins.md) - Plugin system
- [Rolldown Options](advanced-rolldown-options.md) - Build options
- [Watch Mode](option-watch-mode.md) - Development workflow
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