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

View on GitHub
# Executable - `exe`

**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html).

## Requirements

- Node.js >= 25.5.0 (ESM support requires >= 25.7.0)
- Not supported in Bun or Deno

## Basic Usage

```ts
export default defineConfig({
  entry: ['src/cli.ts'],
  exe: true,
})
```

## Behavior When Enabled

- Default output format changes from `esm` to `cjs` (unless Node.js >= 25.7.0)
- Declaration file generation (`dts`) is disabled by default
- Code splitting is disabled
- Only single entry points are supported
- Legacy CJS warnings are suppressed

## Advanced Configuration

```ts
export default defineConfig({
  entry: ['src/cli.ts'],
  exe: {
    fileName: 'my-tool',
    seaConfig: {
      disableExperimentalSEAWarning: true,
      useCodeCache: true,
      useSnapshot: false,
    },
  },
})
```

## `ExeOptions`

| Option | Type | Description |
|--------|------|-------------|
| `seaConfig` | `Omit<SeaConfig, 'main' \| 'output' \| 'mainFormat'>` | Node.js configuration options |
| `fileName` | `string \| ((chunk) => string)` | Custom output file name (without `.exe` or platform suffixes) |
| `targets` | `ExeTarget[]` | Cross-platform build targets (requires `@tsdown/exe`) |

## `SeaConfig`

See [Node.js Single Executable Applications documentation](https://nodejs.org/api/single-executable-applications.html).

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `disableExperimentalSEAWarning` | `boolean` | `true` | Disable the experimental warning |
| `useSnapshot` | `boolean` | `false` | Use V8 snapshot |
| `useCodeCache` | `boolean` | `false` | Use V8 code cache |
| `execArgv` | `string[]` | - | Extra Node.js arguments |
| `execArgvExtension` | `'none' \| 'env' \| 'cli'` | `'env'` | How to extend execArgv |
| `assets` | `Record<string, string>` | - | Assets to embed |

## Cross-Platform Builds

Install `@tsdown/exe` to build executables for multiple platforms from a single machine:

```bash
pnpm add -D @tsdown/exe
```

```ts
export default defineConfig({
  entry: ['src/cli.ts'],
  exe: {
    targets: [
      { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },
      { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },
      { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },
    ],
  },
})
```

This downloads the target platform's Node.js binary, caches it locally, and produces platform-suffixed output:

```
dist/
  cli-linux-x64
  cli-darwin-arm64
  cli-win-x64.exe
```

### `ExeTarget`

| Field | Type | Description |
|-------|------|-------------|
| `platform` | `'win' \| 'darwin' \| 'linux'` | Target OS (nodejs.org naming) |
| `arch` | `'x64' \| 'arm64'` | Target CPU architecture |
| `nodeVersion` | `string` | Node.js version (must be `>=25.7.0`) |

### Caching

Downloaded Node.js binaries are cached in system cache directories:
- **macOS:** `~/Library/Caches/tsdown/node/`
- **Linux:** `~/.cache/tsdown/node/`
- **Windows:** `%LOCALAPPDATA%/tsdown/Caches/node/`

## Platform Notes

- On macOS, the executable is automatically codesigned (ad-hoc) for Gatekeeper compatibility
- On Windows, the `.exe` extension is automatically appended
- When `targets` is specified, `seaConfig.executable` is ignored

## CLI

```bash
tsdown --exe
tsdown src/cli.ts --exe
```
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