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-shims.md

View on GitHub
# Shims

Add compatibility between ESM and CommonJS module systems.

## Overview

Shims provide small pieces of code that bridge the gap between CommonJS (CJS) and ECMAScript Modules (ESM), enabling cross-module-system compatibility.

## What Shims Provide

### ESM Output (when enabled)

With `shims: true`, adds CommonJS variables to ESM:

- `__dirname` - Current directory path
- `__filename` - Current file path

### ESM Output (automatic)

Always added when using `require` in ESM on Node.js:

- `require` function via `createRequire(import.meta.url)`

### CJS Output (automatic)

Always added to CommonJS output:

- `import.meta.url`
- `import.meta.dirname`
- `import.meta.filename`

## Usage

### CLI

```bash
tsdown --shims
```

### Config File

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

## Generated Code

### ESM with Shims

**Source:**
```ts
console.log(__dirname)
console.log(__filename)
```

**Output (shims: true):**
```js
import { fileURLToPath } from 'node:url'
import { dirname } from 'node:path'

const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)

console.log(__dirname)
console.log(__filename)
```

### ESM with require

**Source:**
```ts
const mod = require('some-module')
```

**Output (automatic on Node.js):**
```js
import { createRequire } from 'node:module'
const require = createRequire(import.meta.url)

const mod = require('some-module')
```

### CJS with import.meta

**Source:**
```ts
console.log(import.meta.url)
console.log(import.meta.dirname)
```

**Output (automatic):**
```js
const import_meta = {
  url: require('url').pathToFileURL(__filename).toString(),
  dirname: __dirname,
  filename: __filename
}

console.log(import_meta.url)
console.log(import_meta.dirname)
```

## Common Patterns

### Node.js CLI Tool

```ts
export default defineConfig({
  entry: ['src/cli.ts'],
  format: ['esm'],
  platform: 'node',
  shims: true,  // Add __dirname, __filename
})
```

### Dual Format Library

```ts
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  platform: 'node',
  shims: true,  // ESM gets __dirname/__filename
                // CJS gets import.meta.* (automatic)
})
```

### Server-Side Code

```ts
export default defineConfig({
  entry: ['src/server.ts'],
  format: ['esm'],
  platform: 'node',
  shims: true,
  deps: {
    neverBundle: [/.*/],  // External all deps
  },
})
```

### File System Operations

```ts
// Source code
import { readFileSync } from 'fs'
import { join } from 'path'

// Read file relative to current module
const content = readFileSync(join(__dirname, 'data.json'), 'utf-8')
```

```ts
// tsdown config
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm'],
  shims: true,  // Enables __dirname
})
```

## When to Use Shims

### Use `shims: true` when:

- ✅ Building Node.js tools/CLIs
- ✅ Code uses `__dirname` or `__filename`
- ✅ Need file system operations relative to module
- ✅ Migrating from CommonJS to ESM
- ✅ Need cross-format compatibility

### Don't need shims when:

- ❌ Browser-only code
- ❌ No file system operations
- ❌ Using only `import.meta.url`
- ❌ Pure ESM without CJS variables

## Performance Impact

### Runtime Overhead

Shims add minimal runtime overhead:

```js
// Added to output when shims enabled
import { fileURLToPath } from 'node:url'
import { dirname } from 'node:path'

const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
```

### Tree Shaking

If `__dirname` or `__filename` are not used, they're automatically removed during bundling (no overhead).

## Platform Considerations

### Node.js Platform

```ts
export default defineConfig({
  platform: 'node',
  format: ['esm'],
  shims: true,  // Recommended for Node.js
})
```

- `require` shim added automatically
- `__dirname` and `__filename` available with `shims: true`

### Browser Platform

```ts
export default defineConfig({
  platform: 'browser',
  format: ['esm'],
  shims: false,  // Not needed for browser
})
```

- Shims not needed (no Node.js variables)
- Will cause warnings if Node.js APIs used

### Neutral Platform

```ts
export default defineConfig({
  platform: 'neutral',
  format: ['esm'],
  shims: false,  // Avoid platform-specific code
})
```

- Avoid shims for maximum portability

## CLI Examples

```bash
# Enable shims
tsdown --shims

# ESM with shims for Node.js
tsdown --format esm --platform node --shims

# Dual format with shims
tsdown --format esm --format cjs --shims
```

## Troubleshooting

### `__dirname is not defined`

Enable shims:

```ts
export default defineConfig({
  shims: true,
})
```

### `require is not defined` in ESM

Automatic on Node.js platform. If not working:

```ts
export default defineConfig({
  platform: 'node',  // Ensure Node.js platform
})
```

### Import.meta not working in CJS

Automatic - no configuration needed. If still failing, check output format:

```ts
export default defineConfig({
  format: ['cjs'],  // Shims added automatically
})
```

## Tips

1. **Enable for Node.js tools** - Use `shims: true` for CLIs and servers
2. **Skip for browsers** - Not needed for browser code
3. **No overhead if unused** - Automatically tree-shaken
4. **Automatic require shim** - No config needed for `require` in ESM
5. **CJS shims automatic** - `import.meta.*` always available in CJS

## Related Options

- [Platform](option-platform.md) - Runtime environment
- [Output Format](option-output-format.md) - Module formats
- [Target](option-target.md) - Syntax transformations
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