{"owner":"crxjs","repo":"chrome-extension-tools","hasSkills":true,"totalSkillsCount":43,"totalTokensCount":51137,"categories":["anthropic-skill","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/tsdown/README.md",".agents/skills/tsdown/SKILL.md",".agents/skills/tsdown/references/README.md",".agents/skills/tsdown/references/advanced-benchmark.md",".agents/skills/tsdown/references/advanced-ci.md",".agents/skills/tsdown/references/advanced-hooks.md",".agents/skills/tsdown/references/advanced-plugins.md",".agents/skills/tsdown/references/advanced-programmatic.md",".agents/skills/tsdown/references/advanced-rolldown-options.md",".agents/skills/tsdown/references/guide-getting-started.md",".agents/skills/tsdown/references/guide-introduction.md",".agents/skills/tsdown/references/guide-migrate-from-tsup.md",".agents/skills/tsdown/references/option-cjs-default.md",".agents/skills/tsdown/references/option-cleaning.md",".agents/skills/tsdown/references/option-config-file.md",".agents/skills/tsdown/references/option-copy.md",".agents/skills/tsdown/references/option-css.md",".agents/skills/tsdown/references/option-dependencies.md",".agents/skills/tsdown/references/option-dts.md",".agents/skills/tsdown/references/option-entry.md",".agents/skills/tsdown/references/option-exe.md",".agents/skills/tsdown/references/option-lint.md",".agents/skills/tsdown/references/option-log-level.md",".agents/skills/tsdown/references/option-minification.md",".agents/skills/tsdown/references/option-output-directory.md",".agents/skills/tsdown/references/option-output-format.md",".agents/skills/tsdown/references/option-package-exports.md",".agents/skills/tsdown/references/option-platform.md",".agents/skills/tsdown/references/option-root.md",".agents/skills/tsdown/references/option-shims.md",".agents/skills/tsdown/references/option-sourcemap.md",".agents/skills/tsdown/references/option-target.md",".agents/skills/tsdown/references/option-tree-shaking.md",".agents/skills/tsdown/references/option-unbundle.md",".agents/skills/tsdown/references/option-watch-mode.md",".agents/skills/tsdown/references/recipe-react.md",".agents/skills/tsdown/references/recipe-solid.md",".agents/skills/tsdown/references/recipe-svelte.md",".agents/skills/tsdown/references/recipe-vue.md",".agents/skills/tsdown/references/recipe-wasm.md",".agents/skills/tsdown/references/reference-cli.md","packages/rollup-plugin/README.md","packages/vite-plugin/README.md"],"skills":{".agents/skills/tsdown/README.md":"# tsdown Skills\n\nAgent skills that help AI coding agents understand and work with [tsdown](https://tsdown.dev), the elegant library bundler.\n\n## Installation\n\n```bash\nnpx skills add rolldown/tsdown\n```\n\nThis will install all tsdown skills (including the migration skill). To install only the tsdown skill:\n\n```bash\nnpx skills add rolldown/tsdown --skill tsdown\n```\n\n## What's Included\n\nThe tsdown skill provides Claude Code with knowledge about:\n\n- **Core Concepts** - What tsdown is, why use it, key features\n- **Configuration** - Config file formats, options, multiple configs, workspace support\n- **Build Options** - Entry points, output formats, type declarations, targets\n- **Dependency Handling** - External/inline dependencies, auto-externalization\n- **Output Enhancement** - Shims, CJS defaults, package exports\n- **Framework Support** - React, Vue, Solid, Svelte integration\n- **Advanced Features** - Plugins, hooks, programmatic API, Rolldown options\n- **CLI Commands** - All CLI options and usage patterns\n- **Migration** - Migrating from tsup to tsdown\n\n## Usage\n\nOnce installed, Claude Code will automatically use tsdown knowledge when:\n\n- Building TypeScript/JavaScript libraries\n- Configuring bundlers for library projects\n- Setting up type declaration generation\n- Working with multi-format builds (ESM, CJS, IIFE, UMD)\n- Migrating from tsup\n- Building framework component libraries\n\n### Example Prompts\n\n```\nSet up tsdown to build my TypeScript library with ESM and CJS formats\n```\n\n```\nConfigure tsdown to generate type declarations and bundle for browsers\n```\n\n```\nAdd React support to my tsdown config with Fast Refresh\n```\n\n```\nHelp me migrate from tsup to tsdown\n```\n\n```\nSet up a monorepo build with tsdown workspace support\n```\n\n## Related Skills\n\n- **[tsdown-migrate](https://github.com/rolldown/tsdown/tree/main/skills/tsdown-migrate)** - Dedicated skill for migrating from tsup to tsdown, with complete option mappings, config transformations, and troubleshooting guidance.\n\n## Documentation\n\n- [tsdown Documentation](https://tsdown.dev)\n- [GitHub Repository](https://github.com/rolldown/tsdown)\n- [Rolldown](https://rolldown.rs)\n- [Migration Guide](https://tsdown.dev/guide/migrate-from-tsup)\n\n## License\n\nMIT\n",".agents/skills/tsdown/SKILL.md":"---\nname: tsdown\ndescription: 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.\n---\n\n# tsdown - The Elegant Library Bundler\n\nBlazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.\n\n## Runtime Requirement\n\n`tsdown` requires **Node.js 22.18.0 or higher to run** (build-time only). However, the bundled output can target much lower Node.js versions via the [`target`](references/option-target.md) option, so libraries built with tsdown are **not locked to Node.js 22+ at runtime**.\n\nIf your package needs to support Node.js 18 / 20:\n\n- **Build with Node.js 22+ in CI** (e.g. set `target: 'node18'` or `target: 'node20'`).\n- **Test the built output (or the packed tarball) on the lower Node.js versions** you intend to support — e.g. using a matrix job that runs the published package's tests on Node.js 18 / 20 / 22.\n\n## When to Use\n\n- Building TypeScript/JavaScript libraries for npm\n- Generating TypeScript declaration files (.d.ts)\n- Bundling for multiple formats (ESM, CJS, IIFE, UMD)\n- Optimizing bundles with tree shaking and minification\n- Migrating from tsup with minimal changes\n- Building React, Vue, Solid, or Svelte component libraries\n\n## Quick Start\n\n```bash\n# Install\npnpm add -D tsdown\n\n# Basic usage\nnpx tsdown\n\n# With config file\nnpx tsdown --config tsdown.config.ts\n\n# Watch mode\nnpx tsdown --watch\n\n# Migrate from tsup\nnpx tsdown-migrate\n```\n\n## Basic Configuration\n\n```ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n## Core References\n\n| Topic | Description | Reference |\n|-------|-------------|-----------|\n| Getting Started | Installation, first bundle, CLI basics | [guide-getting-started](references/guide-getting-started.md) |\n| Configuration File | Config file formats, multiple configs, workspace | [option-config-file](references/option-config-file.md) |\n| CLI Reference | All CLI commands and options | [reference-cli](references/reference-cli.md) |\n| Migrate from tsup | Migration guide and compatibility notes | [guide-migrate-from-tsup](references/guide-migrate-from-tsup.md) |\n| Plugins | Rolldown, Rollup, Unplugin support | [advanced-plugins](references/advanced-plugins.md) |\n| Hooks | Lifecycle hooks for custom logic | [advanced-hooks](references/advanced-hooks.md) |\n| Programmatic API | Build from Node.js scripts, in-memory builds (`write: false`) | [advanced-programmatic](references/advanced-programmatic.md) |\n| Rolldown Options | Pass options directly to Rolldown | [advanced-rolldown-options](references/advanced-rolldown-options.md) |\n| CI Environment | CI detection, `'ci-only'` / `'local-only'` values | [advanced-ci](references/advanced-ci.md) |\n\n> For comprehensive migration assistance with complete option mappings, install the dedicated [`tsdown-migrate`](../tsdown-migrate/SKILL.md) skill: `npx skills add rolldown/tsdown --skill tsdown-migrate`\n\n## Build Options\n\n| Option | Usage | Reference |\n|--------|-------|-----------|\n| Entry points | `entry: ['src/*.ts', '!**/*.test.ts']` | [option-entry](references/option-entry.md) |\n| Output formats | `format: ['esm', 'cjs', 'iife', 'umd']` | [option-output-format](references/option-output-format.md) |\n| Output directory | `outDir: 'dist'`, `outExtensions` | [option-output-directory](references/option-output-directory.md) |\n| Type declarations | `dts: true`, `dts: { sourcemap, compilerOptions, vue }` | [option-dts](references/option-dts.md) |\n| Target environment | `target: 'es2020'`, `target: 'esnext'` | [option-target](references/option-target.md) |\n| Platform | `platform: 'node'`, `platform: 'browser'` | [option-platform](references/option-platform.md) |\n| Tree shaking | `treeshake: true`, custom options | [option-tree-shaking](references/option-tree-shaking.md) |\n| Minification | `minify: true`, `minify: 'dce-only'` | [option-minification](references/option-minification.md) |\n| Source maps | `sourcemap: true`, `'inline'`, `'hidden'` | [option-sourcemap](references/option-sourcemap.md) |\n| Watch mode | `watch: true`, watch options | [option-watch-mode](references/option-watch-mode.md) |\n| Cleaning | `clean: true`, clean patterns | [option-cleaning](references/option-cleaning.md) |\n| Log level | `logLevel: 'silent'`, `failOnWarn: false`, `suppressWarnings: [...]` | [option-log-level](references/option-log-level.md) |\n\n## Dependency Handling\n\n| Feature | Usage | Reference |\n|---------|-------|-----------|\n| Never bundle | `deps: { neverBundle: ['react', /^@myorg\\//] }` | [option-dependencies](references/option-dependencies.md) |\n| Always bundle | `deps: { alwaysBundle: ['dep-to-bundle'] }` | [option-dependencies](references/option-dependencies.md) |\n| Only bundle | `deps: { onlyBundle: ['cac', 'bumpp'] }` - Whitelist | [option-dependencies](references/option-dependencies.md) |\n| Only import | `deps: { onlyImport: ['cac'] }` - Whitelist runtime imports in output | [option-dependencies](references/option-dependencies.md) |\n| Externalize all | `deps: { neverBundle: true }` | [option-dependencies](references/option-dependencies.md) |\n| Resolve subpaths | `deps: { resolveDepSubpath: true }` - Resolve external subpath imports (default `false`) | [option-dependencies](references/option-dependencies.md) |\n| Auto external | Automatic dependency/peer/optional externalization | [option-dependencies](references/option-dependencies.md) |\n\n## Output Enhancement\n\n| Feature | Usage | Reference |\n|---------|-------|-----------|\n| Shims | `shims: true` - Add ESM/CJS compatibility | [option-shims](references/option-shims.md) |\n| CJS default | `cjsDefault: true` (default) / `false` | [option-cjs-default](references/option-cjs-default.md) |\n| Package exports | `exports: true` - Generate exports field | [option-package-exports](references/option-package-exports.md) |\n| CSS handling | **[experimental]** `css: { ... }` — full pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, code splitting; requires `@tsdown/css` | [option-css](references/option-css.md) |\n| CSS modules | `css: { modules: { localsConvention: 'camelCase' } }` — scoped class names for `.module.css` files | [option-css](references/option-css.md) |\n| CSS inject | `css: { inject: true }` — preserve CSS imports in JS output | [option-css](references/option-css.md) |\n| Copy files | `copy: 'public'` or `copy: { from, to, flatten, rename }` - Copy static assets to output | [option-copy](references/option-copy.md) |\n| Unbundle mode | `unbundle: true` - Preserve directory structure | [option-unbundle](references/option-unbundle.md) |\n| Root directory | `root: 'src'` - Control output directory mapping | [option-root](references/option-root.md) |\n| Executable | **[experimental]** `exe: true` - Bundle as standalone executable, cross-platform via `@tsdown/exe` | [option-exe](references/option-exe.md) |\n| Package validation | `publint: true`, `attw: true` - Validate package | [option-lint](references/option-lint.md) |\n\n## Framework & Runtime Support\n\n| Framework | Guide | Reference |\n|-----------|-------|-----------|\n| React | JSX transform, React Compiler | [recipe-react](references/recipe-react.md) |\n| Vue | SFC support, JSX | [recipe-vue](references/recipe-vue.md) |\n| Solid | SolidJS JSX transform | [recipe-solid](references/recipe-solid.md) |\n| Svelte | Svelte component libraries (source distribution recommended) | [recipe-svelte](references/recipe-svelte.md) |\n| WASM | WebAssembly modules via `rolldown-plugin-wasm` | [recipe-wasm](references/recipe-wasm.md) |\n\n## Common Patterns\n\n### Basic Library Bundle\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### Browser Library (IIFE/UMD)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n globalName: 'MyLib',\n platform: 'browser',\n minify: true,\n})\n```\n\n### React Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.tsx'],\n format: ['esm', 'cjs'],\n dts: true,\n deps: {\n neverBundle: ['react', 'react-dom'],\n },\n inputOptions: {\n jsx: { runtime: 'automatic' },\n },\n})\n```\n\n### Preserve Directory Structure\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n unbundle: true, // Preserve file structure\n format: ['esm'],\n dts: true,\n})\n```\n\n### CI-Aware Configuration\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n failOnWarn: 'ci-only', // opt-in: fail on warnings in CI\n publint: 'ci-only',\n attw: 'ci-only',\n})\n```\n\n### WASM Support\n\n```ts\nimport { wasm } from 'rolldown-plugin-wasm'\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [wasm()],\n})\n```\n\n### Library with CSS and Sass\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n target: 'chrome100',\n css: {\n preprocessorOptions: {\n scss: {\n additionalData: `@use \"src/styles/variables\" as *;`,\n },\n },\n },\n})\n```\n\n### Standalone Executable\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: true,\n})\n```\n\n### Cross-Platform Executable (requires `@tsdown/exe`)\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [\n { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },\n { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },\n { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },\n ],\n },\n})\n```\n\n### Advanced with Hooks\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n hooks: {\n 'build:before': async (context) => {\n console.log('Building...')\n },\n 'build:done': async (context) => {\n console.log('Build complete!')\n },\n },\n})\n```\n\n## Configuration Features\n\n### Multiple Configs\n\nExport an array for multiple build configurations:\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n },\n {\n entry: ['src/cli.ts'],\n format: ['esm'],\n platform: 'node',\n },\n])\n```\n\n### Conditional Config\n\nUse functions for dynamic configuration:\n\n```ts\nexport default defineConfig((options) => {\n const isDev = options.watch\n return {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n }\n})\n```\n\n### Workspace/Monorepo\n\nUse glob patterns to build multiple packages:\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n## CLI Quick Reference\n\n```bash\n# Basic commands\ntsdown # Build once\ntsdown --watch # Watch mode\ntsdown --config custom.ts # Custom config\nnpx tsdown-migrate # Migrate from tsup\n\n# Output options\ntsdown --format esm,cjs # Multiple formats\ntsdown -d lib # Custom output directory (--out-dir)\ntsdown --minify # Enable minification\ntsdown --dts # Generate declarations\ntsdown --exe # Bundle as standalone executable\ntsdown --unbundle # Bundleless mode\ntsdown --copy public # Copy static files to output\n\n# Entry options\ntsdown src/index.ts # Single entry\ntsdown src/*.ts # Glob patterns\ntsdown src/a.ts src/b.ts # Multiple entries\n\n# Workspace / Monorepo\ntsdown -W # Enable workspace mode\ntsdown -W -F my-package # Filter specific package\ntsdown --filter /^pkg-/ # Filter by regex\ntsdown -W --concurrency 4 # Limit parallel Rolldown builds\n\n# Development\ntsdown --watch # Watch mode\ntsdown --sourcemap # Generate source maps\ntsdown --clean # Clean output directory\ntsdown --from-vite # Reuse Vite config\ntsdown --tsconfig tsconfig.build.json # Custom tsconfig\n```\n\n## Best Practices\n\n1. **Always generate type declarations** for TypeScript libraries:\n ```ts\n { dts: true }\n ```\n\n2. **Externalize dependencies** to avoid bundling unnecessary code:\n ```ts\n { deps: { neverBundle: [/^react/, /^@myorg\\//] } }\n ```\n\n3. **Use tree shaking** for optimal bundle size:\n ```ts\n { treeshake: true }\n ```\n\n4. **Enable minification** for production builds:\n ```ts\n { minify: true }\n ```\n\n5. **Add shims** for better ESM/CJS compatibility:\n ```ts\n { shims: true } // Adds __dirname, __filename, etc.\n ```\n\n6. **Auto-generate package.json exports**:\n ```ts\n { exports: true } // Creates proper exports field\n ```\n\n7. **Use watch mode** during development:\n ```bash\n tsdown --watch\n ```\n\n8. **Preserve structure** for utilities with many files:\n ```ts\n { unbundle: true } // Keep directory structure\n ```\n\n9. **Validate packages** in CI before publishing:\n ```ts\n { publint: 'ci-only', attw: 'ci-only' }\n ```\n\n## Resources\n\n- Documentation: https://tsdown.dev\n- GitHub: https://github.com/rolldown/tsdown\n- Rolldown: https://rolldown.rs\n- Migration Guide: https://tsdown.dev/guide/migrate-from-tsup\n",".agents/skills/tsdown/references/README.md":"# tsdown Skill References\n\nThis directory contains detailed reference documentation for the tsdown skill.\n\n## Created Files (38 total)\n\n### Core Guides (3)\n- ✅ `guide-getting-started.md` - Installation, first bundle, CLI basics\n- ✅ `guide-migrate-from-tsup.md` - Migration guide from tsup\n- ✅ `guide-introduction.md` - Introduction and key features\n\n### Configuration Options (22)\n- ✅ `option-config-file.md` - Config file formats, loaders, workspace\n- ✅ `option-entry.md` - Entry point configuration with globs\n- ✅ `option-output-format.md` - Output formats (ESM, CJS, IIFE, UMD)\n- ✅ `option-output-directory.md` - Output directory and extensions\n- ✅ `option-dts.md` - TypeScript declaration generation\n- ✅ `option-target.md` - Target environment (ES2020, ESNext, etc.)\n- ✅ `option-platform.md` - Platform (node, browser, neutral)\n- ✅ `option-dependencies.md` - External and inline dependencies\n- ✅ `option-sourcemap.md` - Source map generation\n- ✅ `option-minification.md` - Minification (`boolean | 'dce-only' | MinifyOptions`)\n- ✅ `option-tree-shaking.md` - Tree shaking configuration\n- ✅ `option-cleaning.md` - Output directory cleaning\n- ✅ `option-watch-mode.md` - Watch mode configuration\n- ✅ `option-shims.md` - ESM/CJS compatibility shims\n- ✅ `option-package-exports.md` - Auto-generate package.json exports\n- ✅ `option-css.md` - CSS handling (experimental, full pipeline: preprocessors, Lightning CSS, PostCSS, code splitting)\n- ✅ `option-unbundle.md` - Preserve directory structure\n- ✅ `option-root.md` - Root directory for output structure mapping\n- ✅ `option-copy.md` - Copy static files to output\n- ✅ `option-cjs-default.md` - CommonJS default export handling\n- ✅ `option-log-level.md` - Logging configuration\n- ✅ `option-lint.md` - Package validation (publint & attw)\n\n### Executable (1)\n- ✅ `option-exe.md` - Standalone executable bundling (Node.js SEA)\n\n### Advanced Topics (6)\n- ✅ `advanced-plugins.md` - Rolldown, Rollup, Unplugin support\n- ✅ `advanced-hooks.md` - Lifecycle hooks system\n- ✅ `advanced-programmatic.md` - Node.js API usage\n- ✅ `advanced-rolldown-options.md` - Pass options to Rolldown\n- ✅ `advanced-ci.md` - CI environment detection and CI-aware options\n\n### Advanced (continued)\n- ✅ `advanced-benchmark.md` - Performance benchmarks\n\n### Framework Recipes (5)\n- ✅ `recipe-react.md` - React library setup with JSX\n- ✅ `recipe-vue.md` - Vue library setup with SFC\n- ✅ `recipe-solid.md` - Solid.js library setup\n- ✅ `recipe-svelte.md` - Svelte component libraries\n- ✅ `recipe-wasm.md` - WASM module support\n\n### Reference (1)\n- ✅ `reference-cli.md` - Complete CLI command reference\n\n## Coverage Status\n\n**Created:** 38 files (100% complete)\n\n## Current Skill Features\n\nThe tsdown skill now includes comprehensive coverage of:\n\n### ✅ Core Functionality\n- Getting started and installation\n- Entry points and glob patterns\n- Output formats (ESM, CJS, IIFE, UMD)\n- TypeScript declarations\n- Configuration file setup\n- CLI reference\n\n### ✅ Build Options\n- Target environment configuration\n- Platform selection\n- Dependency management\n- Source maps\n- Minification\n- Tree shaking\n- Output cleaning\n- Watch mode\n\n### ✅ Advanced Features\n- Plugins (Rolldown, Rollup, Unplugin)\n- Lifecycle hooks\n- ESM/CJS shims\n- Package exports generation\n- Package validation (publint, attw)\n- Programmatic API (Node.js)\n- Output directory customization\n- CSS handling and modules\n- Unbundle mode\n- CI environment detection and CI-aware options\n\n### ✅ Framework & Runtime Support\n- React with JSX/TSX\n- React Compiler integration\n- Vue with SFC support\n- Vue type generation (vue-tsc)\n- WASM module bundling (rolldown-plugin-wasm)\n\n### ✅ Migration\n- Complete migration guide from tsup\n- Compatibility notes\n\n## Usage\n\nThe skill is now ready for use with comprehensive coverage of core features. Additional files can be added incrementally as needed.\n\n## File Naming Convention\n\nFiles are prefixed by category:\n- `guide-*` - Getting started guides and tutorials\n- `option-*` - Configuration options\n- `advanced-*` - Advanced topics (plugins, hooks, programmatic API)\n- `recipe-*` - Framework-specific recipes\n- `reference-*` - CLI and API reference\n\n## Creating New Reference Files\n\nWhen creating new reference files:\n\n1. **Read source documentation** from `/docs` directory\n2. **Simplify for AI consumption** - concise, actionable content\n3. **Include code examples** - practical, copy-paste ready\n4. **Add cross-references** - link to related options\n5. **Follow naming convention** - use appropriate prefix\n6. **Keep it focused** - one topic per file\n\n## Updating Existing Files\n\nWhen documentation changes:\n\n1. Check git diff: `git diff ..HEAD -- docs/`\n2. Update affected reference files\n3. Update SKILL.md if needed\n4. Update GENERATION.md with new SHA\n\nSee `skills/GENERATION.md` for detailed update instructions.\n",".agents/skills/tsdown/references/advanced-benchmark.md":"# Benchmark\n\ntsdown delivers exceptional performance:\n\n- **~2x faster** than tsup for standard builds\n- **Up to 8x faster** for TypeScript declaration generation\n\nFor detailed comparisons, see [bundler-benchmark](https://gugustinette.github.io/bundler-benchmark/).\n",".agents/skills/tsdown/references/advanced-ci.md":"# CI Environment Support\n\nAutomatically detect CI environments and toggle features based on local vs CI builds.\n\n## Overview\n\ntsdown detects CI from the `CI` environment variable. CI mode is enabled when `process.env.CI` is set to a value other than `0` or `false` (case-insensitive).\n\n## CI-Aware Values\n\nSeveral options accept CI-aware string values:\n\n| Value | Behavior |\n|-------|----------|\n| `true` | Always enabled |\n| `false` | Always disabled |\n| `'ci-only'` | Enabled only in CI, disabled locally |\n| `'local-only'` | Enabled only locally, disabled in CI |\n\n## Supported Options\n\nThese options accept CI-aware values:\n\n- `dts` - TypeScript declaration file generation\n- `publint` - Package lint validation\n- `attw` - \"Are the types wrong\" validation\n- `report` - Bundle size reporting\n- `exports` - Auto-generate `package.json` exports\n- `unused` - Unused dependency check\n- `devtools` - DevTools integration\n- `failOnWarn` - Fail on warnings (defaults to `false`)\n\n## Usage\n\n### String Form\n\n```ts\nexport default defineConfig({\n dts: 'local-only', // Skip DTS in CI for faster builds\n publint: 'ci-only', // Only run publint in CI\n failOnWarn: 'ci-only', // Fail on warnings in CI only (opt-in)\n})\n```\n\n### Object Form\n\nWhen an option takes a configuration object, set `enabled` to a CI-aware value:\n\n```ts\nexport default defineConfig({\n publint: {\n enabled: 'ci-only',\n level: 'error',\n },\n attw: {\n enabled: 'ci-only',\n profile: 'node16',\n },\n})\n```\n\n### Config Function\n\nThe config function receives a `ci` boolean in its context:\n\n```ts\nexport default defineConfig((_, { ci }) => ({\n minify: ci,\n sourcemap: !ci,\n}))\n```\n\n## Typical CI Configuration\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n dts: true,\n failOnWarn: 'ci-only',\n publint: 'ci-only',\n attw: 'ci-only',\n})\n```\n\n## Related Options\n\n- [Package Validation](option-lint.md) - publint and attw configuration\n- [Log Level](option-log-level.md) - `failOnWarn` option details\n",".agents/skills/tsdown/references/advanced-hooks.md":"# Lifecycle Hooks\n\nExtend the build process with lifecycle hooks.\n\n## Overview\n\nHooks provide a way to inject custom logic at specific stages of the build lifecycle. Inspired by [unbuild](https://github.com/unjs/unbuild).\n\n**Recommendation:** Use [plugins](advanced-plugins.md) for most extensions. Use hooks for simple custom tasks or Rolldown plugin injection.\n\n## Usage Patterns\n\n### Object Syntax\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n hooks: {\n 'build:prepare': async (context) => {\n console.log('Build starting...')\n },\n 'build:done': async (context) => {\n console.log('Build complete!')\n },\n },\n})\n```\n\n### Function Syntax\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n hooks(hooks) {\n hooks.hook('build:prepare', () => {\n console.log('Preparing build...')\n })\n\n hooks.hook('build:before', (context) => {\n console.log(`Building format: ${context.format}`)\n })\n },\n})\n```\n\n## Available Hooks\n\n### `build:prepare`\n\nCalled before the build process starts.\n\n**When:** Once per build session\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Setup tasks\n- Validation\n- Environment preparation\n\n**Example:**\n```ts\nhooks: {\n 'build:prepare': async (context) => {\n console.log('Starting build for:', context.options.entry)\n await cleanOldFiles()\n },\n}\n```\n\n### `build:before`\n\nCalled before each Rolldown build.\n\n**When:** Once per format (ESM, CJS, etc.)\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n buildOptions: BuildOptions,\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Modify build options per format\n- Inject plugins dynamically\n- Format-specific setup\n\n**Example:**\n```ts\nhooks: {\n 'build:before': async (context) => {\n console.log(`Building ${context.buildOptions.format} format...`)\n\n // Add format-specific plugin\n if (context.buildOptions.format === 'iife') {\n context.buildOptions.plugins.push(browserPlugin())\n }\n },\n}\n```\n\n### `build:done`\n\nCalled after the build completes.\n\n**When:** Once per build session\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n chunks: RolldownChunk[],\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Post-processing\n- Asset copying\n- Notifications\n- Deployment\n\n**Example:**\n```ts\nhooks: {\n 'build:done': async (context) => {\n console.log(`Built ${context.chunks.length} chunks`)\n\n // Copy additional files\n await copyAssets()\n\n // Send notification\n notifyBuildComplete()\n },\n}\n```\n\n## Common Patterns\n\n### Build Notifications\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': () => {\n console.log('🚀 Starting build...')\n },\n 'build:done': (context) => {\n const size = context.chunks.reduce((sum, c) => sum + c.code.length, 0)\n console.log(`✅ Build complete! Total size: ${size} bytes`)\n },\n },\n})\n```\n\n### Conditional Plugin Injection\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n hooks.hook('build:before', (context) => {\n // Add minification only for production\n if (process.env.NODE_ENV === 'production') {\n context.buildOptions.plugins.push(minifyPlugin())\n }\n })\n },\n})\n```\n\n### Custom File Copy\n\n```ts\nimport { copyFile } from 'fs/promises'\n\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n // Copy README to dist\n await copyFile('README.md', `${context.options.outDir}/README.md`)\n },\n },\n})\n```\n\n### Build Metrics\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': (context) => {\n context.startTime = Date.now()\n },\n 'build:done': (context) => {\n const duration = Date.now() - context.startTime\n console.log(`Build took ${duration}ms`)\n\n // Log chunk sizes\n context.chunks.forEach((chunk) => {\n console.log(`${chunk.fileName}: ${chunk.code.length} bytes`)\n })\n },\n },\n})\n```\n\n### Format-Specific Logic\n\n```ts\nexport default defineConfig({\n format: ['esm', 'cjs', 'iife'],\n hooks: {\n 'build:before': (context) => {\n const format = context.buildOptions.format\n\n if (format === 'iife') {\n // Browser-specific setup\n context.buildOptions.globalName = 'MyLib'\n } else if (format === 'cjs') {\n // Node-specific setup\n context.buildOptions.platform = 'node'\n }\n },\n },\n})\n```\n\n### Deployment Hook\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n if (process.env.DEPLOY === 'true') {\n console.log('Deploying to CDN...')\n await deployToCDN(context.options.outDir)\n }\n },\n },\n})\n```\n\n## Advanced Usage\n\n### Multiple Hooks\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n // Register multiple hooks\n hooks.hook('build:prepare', setupEnvironment)\n hooks.hook('build:prepare', validateConfig)\n\n hooks.hook('build:before', injectPlugins)\n hooks.hook('build:before', logFormat)\n\n hooks.hook('build:done', generateManifest)\n hooks.hook('build:done', notifyComplete)\n },\n})\n```\n\n### Async Hooks\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': async (context) => {\n await fetchRemoteConfig()\n await initializeDatabase()\n },\n 'build:done': async (context) => {\n await uploadToS3(context.chunks)\n await invalidateCDN()\n },\n },\n})\n```\n\n### Error Handling\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n try {\n await riskyOperation()\n } catch (error) {\n console.error('Hook failed:', error)\n // Don't throw - allow build to complete\n }\n },\n },\n})\n```\n\n## Hookable API\n\ntsdown uses [hookable](https://github.com/unjs/hookable) for hooks. Additional methods:\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n // Register hook\n hooks.hook('build:done', handler)\n\n // Register hook once\n hooks.hookOnce('build:prepare', handler)\n\n // Remove hook\n hooks.removeHook('build:done', handler)\n\n // Clear all hooks for event\n hooks.removeHooks('build:done')\n\n // Call hooks manually\n await hooks.callHook('build:done', context)\n },\n})\n```\n\n## Tips\n\n1. **Use plugins** for most extensions\n2. **Hooks for simple tasks** like notifications or file copying\n3. **Async hooks supported** for I/O operations\n4. **Don't throw errors** unless you want to fail the build\n5. **Context is mutable** in `build:before` for advanced use cases\n6. **Multiple hooks allowed** for the same event\n\n## Troubleshooting\n\n### Hook Not Called\n\n- Verify hook name is correct\n- Check hook is registered in config\n- Ensure async hooks are awaited\n\n### Build Fails in Hook\n\n- Add try/catch for error handling\n- Don't throw unless intentional\n- Log errors for debugging\n\n### Context Undefined\n\n- Check which hook you're using\n- Verify context properties available for that hook\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Rolldown Options](advanced-rolldown-options.md) - Build options\n- [Watch Mode](option-watch-mode.md) - Development workflow\n",".agents/skills/tsdown/references/advanced-plugins.md":"# Plugins\n\nExtend tsdown with plugins from multiple ecosystems.\n\n## Overview\n\ntsdown, built on Rolldown, supports plugins from multiple ecosystems to extend and customize the bundling process.\n\n## Supported Ecosystems\n\n### 1. Rolldown Plugins\n\nNative plugins designed for Rolldown:\n\n```ts\nimport RolldownPlugin from 'rolldown-plugin-something'\n\nexport default defineConfig({\n plugins: [RolldownPlugin()],\n})\n```\n\n**Compatibility:** ✅ Full support\n\n### 2. Unplugin\n\nUniversal plugins that work across bundlers:\n\n```ts\nimport UnpluginPlugin from 'unplugin-something'\n\nexport default defineConfig({\n plugins: [UnpluginPlugin.rolldown()],\n})\n```\n\n**Compatibility:** ✅ Most unplugin-* plugins work\n\n**Examples:**\n- `unplugin-vue-components`\n- `unplugin-auto-import`\n- `unplugin-icons`\n\n### 3. Rollup Plugins\n\nMost Rollup plugins work with tsdown:\n\n```ts\nimport RollupPlugin from '@rollup/plugin-something'\n\nexport default defineConfig({\n plugins: [RollupPlugin()],\n})\n```\n\n**Compatibility:** ✅ High compatibility\n\n**Type Issues:** May cause TypeScript errors - use type casting:\n\n```ts\nimport RollupPlugin from 'rollup-plugin-something'\n\nexport default defineConfig({\n plugins: [\n // @ts-expect-error Rollup plugin type mismatch\n RollupPlugin(),\n // Or cast to any\n RollupPlugin() as any,\n ],\n})\n```\n\n### 4. Vite Plugins\n\nSome Vite plugins may work:\n\n```ts\nimport VitePlugin from 'vite-plugin-something'\n\nexport default defineConfig({\n plugins: [\n // @ts-expect-error Vite plugin type mismatch\n VitePlugin(),\n ],\n})\n```\n\n**Compatibility:** ⚠️ Limited - only if not using Vite-specific APIs\n\n**Note:** Improved support planned for future releases.\n\n## Usage\n\n### Basic Plugin Usage\n\n```ts\nimport { defineConfig } from 'tsdown'\nimport SomePlugin from 'some-plugin'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [SomePlugin()],\n})\n```\n\n### Multiple Plugins\n\n```ts\nimport PluginA from 'plugin-a'\nimport PluginB from 'plugin-b'\nimport PluginC from 'plugin-c'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n PluginA(),\n PluginB({ option: true }),\n PluginC(),\n ],\n})\n```\n\n### Conditional Plugins\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n plugins: [\n SomePlugin(),\n options.watch && DevPlugin(),\n !options.watch && ProdPlugin(),\n ].filter(Boolean),\n}))\n```\n\n## Common Plugin Patterns\n\n### JSON Import\n\n```ts\nimport json from '@rollup/plugin-json'\n\nexport default defineConfig({\n plugins: [json()],\n})\n```\n\n### Node Resolve\n\n```ts\nimport { nodeResolve } from '@rollup/plugin-node-resolve'\n\nexport default defineConfig({\n plugins: [nodeResolve()],\n})\n```\n\n### CommonJS\n\n```ts\nimport commonjs from '@rollup/plugin-commonjs'\n\nexport default defineConfig({\n plugins: [commonjs()],\n})\n```\n\n### Replace\n\n```ts\nimport replace from '@rollup/plugin-replace'\n\nexport default defineConfig({\n plugins: [\n replace({\n 'process.env.NODE_ENV': JSON.stringify('production'),\n __VERSION__: JSON.stringify('1.0.0'),\n }),\n ],\n})\n```\n\n### Auto Import\n\n```ts\nimport AutoImport from 'unplugin-auto-import/rolldown'\n\nexport default defineConfig({\n plugins: [\n AutoImport({\n imports: ['vue', 'vue-router'],\n dts: 'src/auto-imports.d.ts',\n }),\n ],\n})\n```\n\n### Vue Components\n\n```ts\nimport Components from 'unplugin-vue-components/rolldown'\n\nexport default defineConfig({\n plugins: [\n Components({\n dts: 'src/components.d.ts',\n }),\n ],\n})\n```\n\n## Framework-Specific Plugins\n\n### React\n\n```ts\nimport react from '@vitejs/plugin-react'\n\nexport default defineConfig({\n entry: ['src/index.tsx'],\n plugins: [\n // @ts-expect-error Vite plugin\n react(),\n ],\n})\n```\n\n### Vue\n\n```ts\nimport vue from '@vitejs/plugin-vue'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n // @ts-expect-error Vite plugin\n vue(),\n ],\n})\n```\n\n### Solid\n\n```ts\nimport solid from 'vite-plugin-solid'\n\nexport default defineConfig({\n entry: ['src/index.tsx'],\n plugins: [\n // @ts-expect-error Vite plugin\n solid(),\n ],\n})\n```\n\n### Svelte\n\n```ts\nimport { svelte } from '@sveltejs/vite-plugin-svelte'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n // @ts-expect-error Vite plugin\n svelte(),\n ],\n})\n```\n\n## Writing Custom Plugins\n\nFollow Rolldown's plugin development guide:\n\n### Basic Plugin Structure\n\n```ts\nimport type { Plugin } from 'rolldown'\n\nfunction myPlugin(): Plugin {\n return {\n name: 'my-plugin',\n\n // Transform hook\n transform(code, id) {\n if (id.endsWith('.custom')) {\n return {\n code: transformCode(code),\n map: null,\n }\n }\n },\n\n // Other hooks...\n }\n}\n```\n\n### Using Custom Plugin\n\n```ts\nimport { myPlugin } from './my-plugin'\n\nexport default defineConfig({\n plugins: [myPlugin()],\n})\n```\n\n## Plugin Configuration\n\n### Plugin-Specific Options\n\nRefer to each plugin's documentation for configuration options.\n\n### Plugin Order\n\nPlugins run in the order they're defined:\n\n```ts\nexport default defineConfig({\n plugins: [\n PluginA(), // Runs first\n PluginB(), // Runs second\n PluginC(), // Runs last\n ],\n})\n```\n\n## Troubleshooting\n\n### Type Errors with Rollup/Vite Plugins\n\nUse type casting:\n\n```ts\nplugins: [\n // Option 1: @ts-expect-error\n // @ts-expect-error Plugin type mismatch\n SomePlugin(),\n\n // Option 2: as any\n SomePlugin() as any,\n]\n```\n\n### Plugin Not Working\n\n1. **Check compatibility** - Verify plugin supports your bundler\n2. **Read documentation** - Follow plugin's setup instructions\n3. **Check plugin order** - Some plugins depend on execution order\n4. **Enable debug mode** - Use `--debug` flag\n\n### Vite Plugin Fails\n\nVite plugins may rely on Vite-specific APIs:\n\n1. **Find Rollup equivalent** - Look for Rollup version of plugin\n2. **Use Unplugin version** - Check for `unplugin-*` alternative\n3. **Wait for support** - Vite plugin support improving\n\n## Resources\n\n- [Rolldown Plugin Development](https://rolldown.rs/apis/plugin-api)\n- [Unplugin Documentation](https://unplugin.unjs.io/)\n- [Rollup Plugins](https://github.com/rollup/plugins)\n- [Vite Plugins](https://vitejs.dev/plugins/)\n\n## Tips\n\n1. **Prefer Rolldown plugins** for best compatibility\n2. **Use Unplugin** for cross-bundler support\n3. **Cast types** for Rollup/Vite plugins\n4. **Test thoroughly** when using cross-ecosystem plugins\n5. **Check plugin docs** for specific configuration\n6. **Write custom plugins** for unique needs\n\n## Related\n\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [Rolldown Options](advanced-rolldown-options.md) - Advanced Rolldown config\n- [React Recipe](recipe-react.md) - React setup with plugins\n- [Vue Recipe](recipe-vue.md) - Vue setup with plugins\n",".agents/skills/tsdown/references/advanced-programmatic.md":"# Programmatic Usage\n\nUse tsdown from JavaScript/TypeScript code.\n\n## Overview\n\ntsdown can be imported and used programmatically in your Node.js scripts, custom build tools, or automation workflows.\n\n## Basic Usage\n\n### Simple Build\n\n```ts\nimport { build } from 'tsdown'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### With Options\n\n```ts\nimport { build } from 'tsdown'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n dts: true,\n minify: true,\n sourcemap: true,\n clean: true,\n})\n```\n\n### In-Memory Output\n\nSet `write: false` to access generated chunks and assets without writing the\nbundle output to disk:\n\n```ts\nimport { build } from 'tsdown'\n\nconst bundles = await build({\n entry: ['src/index.ts'],\n format: 'esm',\n write: false,\n clean: false,\n})\n\nfor (const bundle of bundles) {\n for (const output of bundle.chunks) {\n const contents = output.type === 'chunk' ? output.code : output.source\n console.log(output.fileName, contents)\n }\n}\n```\n\n`build()` currently returns a `TsdownBundle[]`, with one bundle for each\nresolved configuration. Even a single configuration returns an array; its\nin-memory Rolldown outputs are available in `bundle.chunks`.\n\nThe `write` option controls Rolldown's bundle output, while other file operations\nare configured separately. For example, `clean` defaults to `true`, so set\n`clean: false` as above if existing output directories must remain untouched.\nExplicitly enabled features such as `copy` or `exports` may still write files.\n`write: false` is incompatible with watch mode.\n\n## API Reference\n\n### build()\n\nMain function to run a build.\n\n```ts\nimport { build } from 'tsdown'\n\nawait build(options)\n```\n\n**Parameters:**\n- `options` - Build configuration object (same as config file)\n\n**Returns:**\n- `Promise` - One bundle for each resolved configuration\n\n**Throws:**\n- Build errors if compilation fails\n\n## Configuration Object\n\nAll config file options are available:\n\n```ts\nimport { build, defineConfig } from 'tsdown'\n\nconst config = defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: true,\n sourcemap: true,\n deps: {\n neverBundle: ['react', 'react-dom'],\n },\n plugins: [/* plugins */],\n hooks: {\n 'build:done': async () => {\n console.log('Build complete!')\n },\n },\n})\n\nawait build(config)\n```\n\nSee [Config Reference](option-config-file.md) for all options.\n\n## Common Patterns\n\n### Custom Build Script\n\n```ts\n// scripts/build.ts\nimport { build } from 'tsdown'\n\nasync function main() {\n console.log('Building library...')\n\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n })\n\n console.log('Build complete!')\n}\n\nmain().catch(console.error)\n```\n\nRun with:\n```bash\ntsx scripts/build.ts\n```\n\n### Multiple Builds\n\n```ts\nimport { build } from 'tsdown'\n\n// Build main library\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n dts: true,\n})\n\n// Build CLI tool\nawait build({\n entry: ['src/cli.ts'],\n format: ['esm'],\n outDir: 'dist/bin',\n platform: 'node',\n shims: true,\n})\n```\n\n### Conditional Build\n\n```ts\nimport { build } from 'tsdown'\n\nconst isDev = process.env.NODE_ENV === 'development'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n clean: !isDev,\n})\n```\n\n### With Error Handling\n\n```ts\nimport { build } from 'tsdown'\n\ntry {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n })\n console.log('✅ Build successful')\n} catch (error) {\n console.error('❌ Build failed:', error)\n process.exit(1)\n}\n```\n\n### Automated Workflow\n\n```ts\nimport { build } from 'tsdown'\nimport { execSync } from 'child_process'\n\nasync function release() {\n // Clean\n console.log('Cleaning...')\n execSync('rm -rf dist')\n\n // Build\n console.log('Building...')\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: true,\n })\n\n // Test\n console.log('Testing...')\n execSync('npm test')\n\n // Publish\n console.log('Publishing...')\n execSync('npm publish')\n}\n\nrelease().catch(console.error)\n```\n\n### Build with Post-Processing\n\n```ts\nimport { build } from 'tsdown'\nimport { copyFileSync } from 'fs'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n hooks: {\n 'build:done': async () => {\n // Copy additional files\n copyFileSync('README.md', 'dist/README.md')\n copyFileSync('LICENSE', 'dist/LICENSE')\n console.log('Copied additional files')\n },\n },\n})\n```\n\n## Watch Mode\n\nUnfortunately, watch mode is not directly exposed in the programmatic API. Use the CLI for watch mode:\n\n```ts\n// Use CLI for watch mode\nimport { spawn } from 'child_process'\n\nspawn('tsdown', ['--watch'], {\n stdio: 'inherit',\n shell: true,\n})\n```\n\n## Integration Examples\n\n### With Task Runner\n\n```ts\n// gulpfile.js\nimport { build } from 'tsdown'\nimport gulp from 'gulp'\n\ngulp.task('build', async () => {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n })\n})\n\ngulp.task('watch', () => {\n return gulp.watch('src/**/*.ts', gulp.series('build'))\n})\n```\n\n### With Custom CLI\n\n```ts\n// scripts/cli.ts\nimport { build } from 'tsdown'\nimport { Command } from 'commander'\n\nconst program = new Command()\n\nprogram\n .command('build')\n .option('--prod', 'Production build')\n .action(async (options) => {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: options.prod,\n sourcemap: !options.prod,\n })\n })\n\nprogram.parse()\n```\n\n### With CI/CD\n\n```ts\n// .github/scripts/build.ts\nimport { build } from 'tsdown'\n\nconst isCI = process.env.CI === 'true'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: isCI,\n clean: true,\n})\n\n// Upload to artifact storage\nif (isCI) {\n // Upload dist/ to S3, etc.\n}\n```\n\n## TypeScript Support\n\n```ts\n// scripts/build.ts\nimport { build, type UserConfig } from 'tsdown'\n\nconst config: UserConfig = {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n}\n\nawait build(config)\n```\n\n## Tips\n\n1. **Use TypeScript** for type safety\n2. **Handle errors** properly\n3. **Use hooks** for custom logic\n4. **Log progress** for visibility\n5. **Use CLI for watch** mode\n6. **Exit on error** in scripts\n\n## Troubleshooting\n\n### Import Errors\n\nEnsure tsdown is installed:\n```bash\npnpm add -D tsdown\n```\n\n### Type Errors\n\nImport types:\n```ts\nimport type { UserConfig } from 'tsdown'\n```\n\n### Build Fails Silently\n\nAdd error handling:\n```ts\ntry {\n await build(config)\n} catch (error) {\n console.error(error)\n process.exit(1)\n}\n```\n\n### Options Not Working\n\nCheck spelling and types:\n```ts\n// ✅ Correct\n{ format: ['esm', 'cjs'] }\n\n// ❌ Wrong\n{ formats: ['esm', 'cjs'] }\n```\n\n## Related\n\n- [Config File](option-config-file.md) - Configuration options\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [CLI](reference-cli.md) - Command-line interface\n- [Plugins](advanced-plugins.md) - Plugin system\n",".agents/skills/tsdown/references/advanced-rolldown-options.md":"# Customizing Rolldown Options\n\nPass options directly to the underlying Rolldown bundler.\n\n## Overview\n\ntsdown uses [Rolldown](https://rolldown.rs) as its core bundling engine. You can override Rolldown's input and output options directly for fine-grained control.\n\n**Warning:** You should be familiar with Rolldown's behavior before overriding options. Refer to the [Rolldown Config Options](https://rolldown.rs/reference/InputOptions.input) documentation.\n\n## Input Options\n\n### Using an Object\n\n```ts\nexport default defineConfig({\n inputOptions: {\n cwd: './custom-directory',\n },\n})\n```\n\n### Using a Function\n\nDynamically modify options based on the output format:\n\n```ts\nexport default defineConfig({\n inputOptions(inputOptions, format) {\n inputOptions.cwd = './custom-directory'\n return inputOptions\n },\n})\n```\n\n## Output Options\n\n### Using an Object\n\n```ts\nexport default defineConfig({\n outputOptions: {\n legalComments: 'inline',\n },\n})\n```\n\n### Using a Function\n\n```ts\nexport default defineConfig({\n outputOptions(outputOptions, format) {\n if (format === 'esm') {\n outputOptions.legalComments = 'inline'\n }\n return outputOptions\n },\n})\n```\n\n## Common Use Cases\n\n### Preserve Legal Comments\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outputOptions: {\n legalComments: 'inline',\n },\n})\n```\n\n### Custom Working Directory\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n inputOptions: {\n cwd: './packages/my-lib',\n },\n})\n```\n\n### Format-Specific Options\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outputOptions(outputOptions, format) {\n if (format === 'esm') {\n outputOptions.legalComments = 'inline'\n }\n return outputOptions\n },\n})\n```\n\n## When to Use\n\n- When tsdown doesn't expose a specific Rolldown option\n- For format-specific Rolldown customizations\n- For advanced bundling scenarios\n\n## Tips\n\n1. **Read Rolldown docs** before overriding options\n2. **Use functions** for format-specific customization\n3. **Test thoroughly** when overriding defaults\n4. **Prefer tsdown options** when available (e.g., use `minify` instead of setting it via `outputOptions`)\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [Config File](option-config-file.md) - Configuration options\n",".agents/skills/tsdown/references/guide-getting-started.md":"# Getting Started\n\nQuick guide to installing and using tsdown for the first time.\n\n## Installation\n\nInstall tsdown as a development dependency:\n\n```bash\npnpm add -D tsdown\n\n# Optionally install TypeScript if not using isolatedDeclarations\npnpm add -D typescript\n```\n\n**Requirements:**\n- Node.js 22.18.0 or higher **to run tsdown** (build-time only)\n- Experimental support for Deno and Bun\n\n> [!NOTE]\n> The Node.js 22.18+ requirement only applies to the environment that runs `tsdown` itself. The **bundled output** can target much lower Node.js versions via the [`target`](./option-target.md) option, so libraries built with tsdown are not locked to Node.js 22+ at runtime.\n>\n> If your package needs to support Node.js 18 / 20, the recommended workflow is to **build with Node.js 22+ in CI**, then **test the built output (or the packed tarball) against the lower Node.js versions** you intend to support.\n\n## Quick Start Templates\n\nUse `create-tsdown` CLI for instant setup:\n\n```bash\npnpm create tsdown@latest\n```\n\nProvides templates for:\n- Pure TypeScript libraries\n- React component libraries\n- Vue component libraries\n- Ready-to-use configurations\n\n## First Bundle\n\n### 1. Create Source Files\n\n```ts\n// src/index.ts\nimport { hello } from './hello.ts'\nhello()\n\n// src/hello.ts\nexport function hello() {\n console.log('Hello tsdown!')\n}\n```\n\n### 2. Create Config File\n\n```ts\n// tsdown.config.ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n})\n```\n\n### 3. Run Build\n\n```bash\n./node_modules/.bin/tsdown\n```\n\nOutput: `dist/index.mjs`\n\n### 4. Test Output\n\n```bash\nnode dist/index.mjs\n# Output: Hello tsdown!\n```\n\n## Add to npm Scripts\n\n```json\n{\n \"scripts\": {\n \"build\": \"tsdown\"\n }\n}\n```\n\nRun with:\n\n```bash\npnpm build\n```\n\n## CLI Commands\n\n```bash\n# Check version\ntsdown --version\n\n# View help\ntsdown --help\n\n# Build with watch mode\ntsdown --watch\n\n# Build with specific format\ntsdown --format esm,cjs\n\n# Generate type declarations\ntsdown --dts\n```\n\n## Basic Configurations\n\n### TypeScript Library (ESM + CJS)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### Browser Library (IIFE)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n globalName: 'MyLib',\n platform: 'browser',\n minify: true,\n})\n```\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n## Using Plugins\n\nAdd Rolldown, Rollup, or Unplugin plugins:\n\n```ts\nimport SomePlugin from 'some-plugin'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [SomePlugin()],\n})\n```\n\n## Watch Mode\n\nEnable automatic rebuilds on file changes:\n\n```bash\ntsdown --watch\n# or\ntsdown -w\n```\n\n## Next Steps\n\n- Configure [entry points](option-entry.md) with glob patterns\n- Set up [multiple output formats](option-output-format.md)\n- Enable [type declaration generation](option-dts.md)\n- Explore [plugins](advanced-plugins.md) for extended functionality\n- Read [migration guide](guide-migrate-from-tsup.md) if coming from tsup\n",".agents/skills/tsdown/references/guide-introduction.md":"# Introduction\n\n**tsdown** is _The Elegant Library Bundler_ — a fast, simple bundler for TypeScript and JavaScript libraries powered by Rolldown (Rust-based).\n\n## Why tsdown?\n\nBuilt on [Rolldown](https://rolldown.rs), tsdown provides a complete out-of-the-box solution for library authors:\n\n- **Simplified Configuration**: Sensible defaults for library development, minimal boilerplate\n- **Library-Specific Features**: Auto TypeScript declarations, multiple output formats, package validation\n- **Future-Ready**: Official Rolldown project, foundation for Rolldown Vite's Library Mode\n\n## Plugin Ecosystem\n\nSupports the full Rolldown plugin ecosystem plus most Rollup plugins. See [Plugins](advanced-plugins.md).\n\n## What Can It Bundle?\n\n- **TypeScript/JavaScript**: `.ts`, `.js` with modern syntax\n- **TypeScript Declarations**: Auto-generate `.d.ts` files\n- **Multiple Formats**: `esm`, `cjs`, `iife`, `umd`\n- **Assets**: `.json`, `.wasm`, CSS files\n- Built-in tree shaking, minification, and source maps\n\n## Key Differences from Rolldown\n\ntsdown wraps Rolldown with library-specific features:\n- Auto-external `dependencies`, `peerDependencies`, and `optionalDependencies` from `package.json`\n- DTS generation\n- `package.json` exports field generation\n- Watch mode with keyboard shortcuts\n- CSS preprocessing pipeline\n- Executable bundling (SEA)\n\n## Prior Arts\n\nInspired by: Rollup, esbuild, tsup, unbuild. Powered by Rolldown.\n\n## Related\n\n- [Getting Started](guide-getting-started.md) - Installation and first build\n- [Migrate from tsup](guide-migrate-from-tsup.md) - Migration guide\n",".agents/skills/tsdown/references/guide-migrate-from-tsup.md":"# Migrate from tsup\n\nMigration guide for switching from tsup to tsdown.\n\n## Overview\n\ntsdown is built on Rolldown (Rust-based) vs tsup's esbuild, providing faster and more powerful bundling while maintaining compatibility.\n\n## Automatic Migration\n\n### Single Package\n\n```bash\nnpx tsdown-migrate\n```\n\n### Monorepo\n\n```bash\n# Using glob patterns\nnpx tsdown-migrate packages/*\n\n# Multiple directories\nnpx tsdown-migrate packages/foo packages/bar\n```\n\n### Migration Options\n\n- `[...dirs]` - Directories to migrate (supports globs)\n- `--dry-run` or `-d` - Preview changes without modifying files\n- `--yes` or `-y` - Skip confirmation (required in non-interactive environments)\n- `--package-manager ` - Override package manager auto-detection\n- `--no-install` - Skip dependency installation\n\nFor non-interactive callers that install dependencies separately:\n\n```bash\nnpx tsdown-migrate --yes --no-install\n```\n\nWhen installation is enabled, the tool detects the package manager from the\nproject's `packageManager` field or lockfile. If detection fails without a TTY,\npass `--package-manager ` or `--no-install`.\n\n**Important:** Commit your changes before running migration.\n\n## Key Differences\n\n### Default Values\n\n| Option | tsup | tsdown |\n|--------|------|--------|\n| `format` | `['cjs']` | `['esm']` |\n| `clean` | `false` | `true` |\n| `dts` | `false` | Auto-enabled if `types`/`typings` in package.json |\n| `target` | Manual | Auto-read from `engines.node` in package.json |\n\n### Option Renames\n\n| tsup | tsdown |\n|------|--------|\n| `entryPoints` | `entry` |\n| `cjsInterop` | `cjsDefault` |\n| `esbuildPlugins` | `plugins` |\n| `outExtension` | `outExtensions` |\n| `skipNodeModulesBundle` | `deps: { neverBundle: true }` |\n| `publicDir` | `copy` |\n| `bundle: false` | `unbundle: true` |\n| `removeNodeProtocol: true` | `nodeProtocol: 'strip'` |\n| `injectStyle: true` | `css: { inject: true }` |\n\nThe old names were accepted (with deprecation warnings) up to tsdown v0.22.14 and have been removed since — v0.23+ silently ignores them, so a leftover tsup option won't error. Migrate in two stages: install `tsdown@0.22.14` first and resolve every deprecation warning (a warning-free build proves the mapping is complete), then upgrade to the latest version. The `tsdown-migrate` tool installs v0.22.14 for this reason.\n\n### Deprecated but Compatible Options\n\nThese tsup options still work but emit deprecation warnings and will be removed in a future version — migrate them immediately:\n\n| tsup (deprecated) | tsdown (preferred) |\n|-------------------|--------------------|\n| `external: [...]` | `deps: { neverBundle: [...] }` |\n| `noExternal: [...]` | `deps: { alwaysBundle: [...] }` |\n\ntsdown also adds `deps.onlyBundle` for whitelisting allowed bundled packages.\n\n### Unsupported Options\n\n| Option | Status | Alternative |\n|--------|--------|-------------|\n| `splitting: false` | Always enabled | Code splitting cannot be disabled |\n| `metafile` | Not available | Use `devtools: true` for bundle analysis via Vite DevTools |\n| `swc` | Not supported | tsdown uses oxc for transformation (built-in) |\n| `experimentalDts` | Superseded | Use the `dts` option instead |\n| `legacyOutput` | Not supported | No alternative |\n| `plugins` (tsup experimental) | Incompatible | Migrate to Rolldown plugins |\n\n### Plugin System\n\ntsdown uses Rolldown plugins instead of esbuild plugins. If you use unplugin plugins, update the import path:\n\n```ts\n// Before (tsup)\nimport plugin from 'unplugin-example/esbuild'\n// After (tsdown)\nimport plugin from 'unplugin-example/rolldown'\n```\n\n### Output Filename Differences\n\nFor IIFE builds, `tsdown` emits `[name].iife.js`; `tsup` commonly emitted `[name].global.js`. `outExtensions` customizes extensions or suffixes, but it does not remove `.iife` or `.umd`. Use `outputOptions.entryFileNames: '[name].global.js'` to preserve old IIFE filenames.\n\n### New Features in tsdown\n\n#### Node Protocol Control\n\n```ts\nexport default defineConfig({\n nodeProtocol: true, // Add node: prefix (fs → node:fs)\n nodeProtocol: 'strip', // Remove node: prefix (node:fs → fs)\n nodeProtocol: false, // Keep as-is (default)\n})\n```\n\n#### Better Workspace Support\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*', // Build all packages\n})\n```\n\n#### Other tsdown-Exclusive Features\n\n- **`exports`**: Auto-generate the `exports` field in `package.json` with `exports: true`\n- **`publint`** / **`attw`**: Validate your package for common issues and type correctness\n- **`exe`**: Bundle as a Node.js standalone executable (SEA) with `exe: true`\n- **`devtools`**: Vite DevTools integration for bundle analysis with `devtools: true`\n- **`hooks`**: Lifecycle hooks (`build:prepare`, `build:before`, `build:done`)\n- **`css`**: Full CSS pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, and code splitting\n- **`globImport`**: Support for `import.meta.glob` (Vite-style glob imports)\n\n## Migration Checklist\n\n1. **Backup your code** - Commit all changes\n2. **Run migration tool** - `npx tsdown-migrate`\n3. **Review changes** - Check modified config files\n4. **Update scripts** - Change `tsup` to `tsdown` in package.json\n5. **Test build** - Run `pnpm build` to verify\n6. **Adjust config** - Fine-tune based on your needs\n\n## Common Migration Patterns\n\n### Basic Library\n\n**Before (tsup):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs', 'esm'],\n dts: true,\n})\n```\n\n**After (tsdown):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'], // ESM now default\n dts: true,\n clean: true, // Now enabled by default\n})\n```\n\n### With Custom Target\n\n**Before (tsup):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n target: 'es2020',\n})\n```\n\n**After (tsdown):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n // target auto-reads from package.json engines.node\n // Or override explicitly:\n target: 'es2020',\n})\n```\n\n### CLI Scripts\n\n**Before (package.json):**\n```json\n{\n \"scripts\": {\n \"build\": \"tsup\",\n \"dev\": \"tsup --watch\"\n }\n}\n```\n\n**After (package.json):**\n```json\n{\n \"scripts\": {\n \"build\": \"tsdown\",\n \"dev\": \"tsdown --watch\"\n }\n}\n```\n\n## Feature Compatibility\n\n### Supported tsup Features\n\nMost tsup features are supported:\n- ✅ Multiple entry points\n- ✅ Multiple formats (ESM, CJS, IIFE, UMD)\n- ✅ TypeScript declarations\n- ✅ Source maps\n- ✅ Minification\n- ✅ Watch mode\n- ✅ External dependencies\n- ✅ Tree shaking\n- ✅ Shims\n- ✅ Plugins (Rollup compatible)\n\n### Missing Features\n\nSome tsup features are not yet available. Check [GitHub issues](https://github.com/rolldown/tsdown/issues) for status and request features.\n\n## Troubleshooting\n\n### Build Fails After Migration\n\n1. **Check Node.js version** - Requires Node.js 22.18.0+ to run tsdown itself. The bundled output can still target lower Node.js versions via `target`; if you need to support Node.js 18 / 20, build with Node.js 22+ in CI and test the produced output (or packed tarball) on the lower versions.\n2. **Install TypeScript** - Required for DTS generation\n3. **Review config changes** - Ensure format and options are correct\n4. **Check dependencies** - Verify all dependencies are installed\n\n### Different Output\n\n- **Format order** - tsdown defaults to ESM first\n- **Clean behavior** - tsdown cleans outDir by default\n- **Target** - tsdown auto-detects from package.json\n\n### Performance Issues\n\ntsdown should be faster than tsup. If not:\n1. Enable `isolatedDeclarations` for faster DTS generation\n2. Check for large dependencies being bundled\n3. Use `deps.neverBundle: true` if needed\n\n## Getting Help\n\n- [GitHub Issues](https://github.com/rolldown/tsdown/issues) - Report bugs or request features\n- [Documentation](https://tsdown.dev) - Full documentation\n- [Migration Tool](https://github.com/rolldown/tsdown/tree/main/packages/migrate) - Source code\n\n## Acknowledgements\n\ntsdown is heavily inspired by tsup and incorporates parts of its codebase. Thanks to [@egoist](https://github.com/egoist) and the tsup community.\n",".agents/skills/tsdown/references/option-cjs-default.md":"# CJS Default Export\n\nControl how default exports are handled in CommonJS output.\n\n## Overview\n\nThe `cjsDefault` option improves compatibility when generating CommonJS **entry** modules. When enabled (default), entry modules with only a single default export use `module.exports = ...` instead of `exports.default = ...`.\n\n## Type\n\n```ts\ncjsDefault?: boolean // default: true\n```\n\n## Basic Usage\n\n### Enabled (Default)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n cjsDefault: true, // default behavior\n})\n```\n\n### Disabled\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n cjsDefault: false,\n})\n```\n\n## How It Works\n\n### With `cjsDefault: true` (Default)\n\nWhen your module has **only a single default export**, tsdown transforms:\n\n**Source:**\n```ts\n// src/index.ts\nexport default function greet() {\n console.log('Hello, world!')\n}\n```\n\n**Generated CJS:**\n```js\n// dist/index.cjs\nfunction greet() {\n console.log('Hello, world!')\n}\nmodule.exports = greet\n```\n\n**Generated Declaration:**\n```ts\n// dist/index.d.cts\ndeclare function greet(): void\nexport = greet\n```\n\nThis allows consumers to use `const greet = require('your-module')` directly.\n\n### With `cjsDefault: false`\n\nThe default export stays as `exports.default`:\n\n```js\n// dist/index.cjs\nfunction greet() {\n console.log('Hello, world!')\n}\nexports.default = greet\n```\n\nConsumers need `require('your-module').default`.\n\n## Entry Modules Only\n\n`cjsDefault` only applies to **explicit entry modules**. In [unbundle mode](option-unbundle.md), imported modules that are emitted as non-entry chunks keep named CJS exports such as `exports.default`. CJS is considered legacy and is supported in maintenance-only mode, so this behavior will not be extended to non-entry chunks.\n\nIf every source module is intended to be consumed independently, include all of them as entries:\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts'],\n root: 'src',\n format: 'cjs',\n unbundle: true,\n})\n```\n\n## When to Disable\n\n- When your module has both default and named exports\n- When you need consistent `exports.default` behavior\n- When consumers always use ESM imports\n\n## Tips\n\n1. **Leave enabled** for most libraries (default `true`)\n2. **Disable** if you have both default and named exports and need consistent behavior\n3. **Test CJS consumers** to verify compatibility\n\n## Related Options\n\n- [Output Format](option-output-format.md) - Module formats\n- [Shims](option-shims.md) - ESM/CJS compatibility\n",".agents/skills/tsdown/references/option-cleaning.md":"# Output Directory Cleaning\n\nControl how the output directory is cleaned before builds.\n\n## Overview\n\nBy default, tsdown **cleans the output directory** before each build to remove stale files from previous builds.\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Clean enabled (default)\ntsdown\n\n# Disable cleaning\ntsdown --no-clean\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n clean: true, // Default\n})\n```\n\n## Behavior\n\n### With Cleaning (Default)\n\nBefore each build:\n1. All files in `outDir` are removed\n2. Fresh build starts with empty directory\n3. Only current build outputs remain\n\n**Benefits:**\n- No stale files\n- Predictable output\n- Clean slate each build\n\n### Without Cleaning\n\nBuild outputs are added to existing files:\n\n```ts\nexport default defineConfig({\n clean: false,\n})\n```\n\n**Use when:**\n- Multiple builds to same directory\n- Incremental builds\n- Preserving other files\n- Watch mode (faster rebuilds)\n\n## Common Patterns\n\n### Production Build\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n clean: true, // Ensure clean output\n minify: true,\n})\n```\n\n### Development Mode\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n clean: !options.watch, // Don't clean in watch mode\n sourcemap: options.watch,\n}))\n```\n\n### Multiple Builds\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true, // Clean once\n },\n {\n entry: ['src/cli.ts'],\n outDir: 'dist',\n clean: false, // Don't clean, add to same dir\n },\n])\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n clean: true, // Clean each package's dist\n})\n```\n\n### Preserve Static Files\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n clean: false, // Keep manually added files\n outDir: 'dist',\n})\n\n// Manually copy files first\n// Then run tsdown --no-clean\n```\n\n## Clean Patterns\n\n### Selective Cleaning\n\n```ts\nimport { rmSync } from 'fs'\n\nexport default defineConfig({\n clean: false, // Disable auto clean\n hooks: {\n 'build:prepare': () => {\n // Custom cleaning logic\n rmSync('dist/*.js', { force: true })\n // Keep other files\n },\n },\n})\n```\n\n### Clean Specific Directories\n\n```ts\nexport default defineConfig({\n clean: false,\n hooks: {\n 'build:prepare': async () => {\n const { rm } = await import('fs/promises')\n // Only clean specific subdirectories\n await rm('dist/esm', { recursive: true, force: true })\n await rm('dist/cjs', { recursive: true, force: true })\n // Keep dist/types\n },\n },\n})\n```\n\n## Watch Mode Behavior\n\nIn watch mode, cleaning behavior is important:\n\n### Clean on First Build Only\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n watch: options.watch,\n clean: !options.watch, // Only clean initial build\n}))\n```\n\n**Result:**\n- First build: Clean\n- Subsequent rebuilds: Incremental\n\n### Always Clean\n\n```ts\nexport default defineConfig({\n watch: true,\n clean: true, // Clean every rebuild\n})\n```\n\n**Trade-off:** Slower rebuilds, but always fresh output.\n\n## Tips\n\n1. **Leave enabled** for production builds\n2. **Disable in watch mode** for faster rebuilds\n3. **Use multiple configs** carefully with cleaning\n4. **Custom clean logic** via hooks if needed\n5. **Be cautious** - cleaning removes ALL files in outDir\n6. **Test cleaning** - ensure no important files are lost\n\n## Troubleshooting\n\n### Important Files Deleted\n\n- Don't put non-build files in outDir\n- Use separate directory for static files\n- Disable cleaning and manage manually\n\n### Stale Files in Output\n\n- Enable cleaning: `clean: true`\n- Or manually remove before build\n\n### Slow Rebuilds in Watch\n\n- Disable cleaning in watch mode\n- Use incremental builds\n\n## CLI Examples\n\n```bash\n# Default (clean enabled)\ntsdown\n\n# Disable cleaning\ntsdown --no-clean\n\n# Watch mode without cleaning\ntsdown --watch --no-clean\n\n# Multiple formats with cleaning\ntsdown --format esm,cjs --clean\n```\n\n## Examples\n\n### Safe Production Build\n\n```bash\n# Clean before build\nrm -rf dist\ntsdown --clean\n```\n\n### Incremental Development\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n watch: true,\n clean: false, // Faster rebuilds\n sourcemap: true,\n})\n```\n\n### Multi-Stage Build\n\n```ts\n// Stage 1: Clean and build main\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true,\n },\n {\n entry: ['src/utils.ts'],\n outDir: 'dist',\n clean: false, // Add to same directory\n },\n])\n```\n\n## Related Options\n\n- [Output Directory](option-output-directory.md) - Configure outDir\n- [Watch Mode](option-watch-mode.md) - Development workflow\n- [Hooks](advanced-hooks.md) - Custom clean logic\n- [Entry](option-entry.md) - Entry points\n",".agents/skills/tsdown/references/option-config-file.md":"# Configuration File\n\nCentralize and manage build settings with a configuration file.\n\n## Overview\n\ntsdown searches for config files automatically in the current directory and parent directories.\n\n## Supported File Names\n\ntsdown looks for these files (in order):\n- `tsdown.config.ts`\n- `tsdown.config.mts`\n- `tsdown.config.cts`\n- `tsdown.config.js`\n- `tsdown.config.mjs`\n- `tsdown.config.cjs`\n- `tsdown.config.json`\n- `tsdown.config`\n- `package.json` (in `tsdown` field)\n\n## Basic Configuration\n\n### TypeScript Config\n\n```ts\n// tsdown.config.ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### JavaScript Config\n\n```js\n// tsdown.config.js\nexport default {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n}\n```\n\n### JSON Config\n\n```json\n// tsdown.config.json\n{\n \"entry\": [\"src/index.ts\"],\n \"format\": [\"esm\", \"cjs\"],\n \"dts\": true\n}\n```\n\n### Package.json Config\n\n```json\n// package.json\n{\n \"name\": \"my-library\",\n \"tsdown\": {\n \"entry\": [\"src/index.ts\"],\n \"format\": [\"esm\", \"cjs\"],\n \"dts\": true\n }\n}\n```\n\n## Multiple Configurations\n\nBuild multiple outputs with different settings:\n\n```ts\nexport default defineConfig([\n {\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n platform: 'node',\n dts: true,\n },\n {\n entry: 'src/browser.ts',\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n minify: true,\n },\n])\n```\n\nEach configuration runs as a separate build.\n\n## Dynamic Configuration\n\nUse a function for conditional config:\n\n```ts\nexport default defineConfig((options) => {\n const isDev = options.watch\n\n return {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n clean: !isDev,\n }\n})\n```\n\nAvailable options:\n- `watch` - Whether watch mode is enabled\n- Other CLI flags passed to config\n\n## Config Loaders\n\nControl how TypeScript config files are loaded:\n\n### Auto Loader (Default)\n\nUses native TypeScript support if available, otherwise falls back to `unrun`:\n\n```bash\ntsdown # Uses auto loader\n```\n\n### Native Loader\n\nUses runtime's native TypeScript support (Node.js 22.18.0+, Bun, Deno):\n\n```bash\ntsdown --config-loader native\n```\n\n### tsx Loader\n\nUses [tsx](https://tsx.is/) library for loading via its tsImport API. Note: `tsx` is an optional peer dependency — install it manually first.\n\n```bash\npnpm add -D tsx\ntsdown --config-loader tsx\n```\n\n### Unrun Loader\n\nUses [unrun](https://gugustinette.github.io/unrun/) library for loading. Note: `unrun` is an optional peer dependency — install it manually first.\n\n```bash\npnpm add -D unrun\ntsdown --config-loader unrun\n```\n\n**Tip:** Use `tsx` or `unrun` loader if you need to load TypeScript configs without file extensions in Node.js.\n\n## Custom Config Path\n\nSpecify a custom config file location:\n\n```bash\ntsdown --config ./configs/build.config.ts\n# or\ntsdown -c custom-config.ts\n```\n\n## Disable Config File\n\nIgnore config files and use CLI options only:\n\n```bash\ntsdown --no-config src/index.ts --format esm\n```\n\n## Extend Vite/Vitest Config (Experimental)\n\nReuse existing Vite or Vitest configurations:\n\n```bash\n# Extend vite.config.*\ntsdown --from-vite\n\n# Extend vitest.config.*\ntsdown --from-vite vitest\n```\n\n**Note:** Only specific options like `resolve` and `plugins` are reused. Test thoroughly as this feature is experimental.\n\n## Workspace / Monorepo\n\nBuild multiple packages with a single config:\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nEach package directory matching the glob pattern will be built with the same configuration.\n\n## Common Patterns\n\n### Library with Multiple Builds\n\n```ts\nexport default defineConfig([\n // Node.js build\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n platform: 'node',\n dts: true,\n },\n // Browser build\n {\n entry: ['src/browser.ts'],\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n },\n])\n```\n\n### Development vs Production\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !options.watch,\n sourcemap: options.watch ? true : false,\n clean: !options.watch,\n}))\n```\n\n### Monorepo Root Config\n\n```ts\n// Root tsdown.config.ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n // Shared config for all packages\n})\n```\n\n### Per-Package Override\n\n```ts\n// packages/special/tsdown.config.ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm'], // Override: only ESM\n platform: 'browser', // Override: browser only\n})\n```\n\n## Config Precedence\n\nWhen multiple configs exist:\n\n1. CLI options (highest priority)\n2. Config file specified with `--config`\n3. Auto-discovered config files\n4. Package.json `tsdown` field\n5. Default values\n\n## Tips\n\n1. **Use TypeScript config** for type checking and autocomplete\n2. **Use defineConfig** helper for better DX\n3. **Export arrays** for multiple build configurations\n4. **Use functions** for dynamic/conditional configs\n5. **Keep configs simple** - prefer convention over configuration\n6. **Use workspace** for monorepo builds\n7. **Test experimental features** thoroughly before production use\n\n## Related Options\n\n- [Entry](option-entry.md) - Configure entry points\n- [Output Format](option-output-format.md) - Output formats\n- [Watch Mode](option-watch-mode.md) - Watch mode configuration\n",".agents/skills/tsdown/references/option-copy.md":"# Copy Files\n\nCopy static files and directories into the build output.\n\n## Overview\n\nThe `copy` option copies assets that should be distributed without being processed by the bundler — images, fonts, license files, etc.\n\n## Basic Usage\n\n### CLI\n\n```bash\ntsdown --copy public\n```\n\nWith the default `outDir` of `dist`, `public/favicon.svg` is copied to `dist/public/favicon.svg`.\n\n### Config File\n\n```ts\nexport default defineConfig({\n copy: 'public',\n})\n```\n\nMultiple paths, glob patterns, or object entries in an array:\n\n```ts\nexport default defineConfig({\n copy: [\n 'LICENSE',\n {\n from: ['public/**/*', '!public/**/*.map'],\n to: 'dist/assets',\n flatten: false,\n },\n ],\n})\n```\n\nGlob patterns support negation with a leading `!`.\n\n**Note:** Relative source and destination paths are resolved from the project root (`cwd`), not from `outDir`.\n\n## Object Options\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `from` | `string \\| string[]` | Required | Source path or glob pattern; arrays can include negated patterns |\n| `to` | `string` | `outDir` | Destination path, resolved from the project root |\n| `flatten` | `boolean` | `true` | Place matched files directly in `to`. Set `false` to preserve the directory structure below the first segment |\n| `rename` | `string \\| ((name, extension, fullPath) => string)` | — | Change the destination name. Callback receives the extension without a leading dot and the absolute path |\n| `verbose` | `boolean` | `false` | Log each copied source and destination |\n\n### Preserve Directory Structure\n\n```ts\nexport default defineConfig({\n copy: {\n from: 'assets/**/*',\n to: 'dist/public',\n flatten: false,\n },\n})\n```\n\n`assets/fonts/inter.woff2` → `dist/public/fonts/inter.woff2`.\n\n### Rename Copied Items\n\n```ts\nexport default defineConfig({\n copy: [\n { from: 'src/file.txt', to: 'dist', rename: 'file.md' },\n {\n from: 'src/file.txt',\n to: 'dist',\n rename: (name, extension) => `${name}-renamed.${extension}`,\n },\n ],\n})\n```\n\nCreates `dist/file.md` and `dist/file-renamed.txt`.\n\n## Dynamic Configuration\n\n`copy` can be a sync or async callback receiving the resolved tsdown config:\n\n```ts\nexport default defineConfig({\n copy: ({ outDir }) => ({\n from: ['assets/**/*', '!assets/**/*.map'],\n to: `${outDir}/assets`,\n flatten: false,\n }),\n})\n```\n\n## Build and Watch Behavior\n\n- Copying runs after the bundle output is produced; files are copied without passing through Rolldown transforms.\n- A top-level `copy` option runs only once for a multi-format build; a format-specific override can define `copy` again for that format.\n- In watch mode, matched source files are watched as build dependencies — changing one triggers a rebuild and copies the current files again.\n\n## Related Options\n\n- [Output Directory](option-output-directory.md) - Where output goes\n- [Cleaning](option-cleaning.md) - Output directory cleanup\n- [Watch Mode](option-watch-mode.md) - Watch mode behavior\n",".agents/skills/tsdown/references/option-css.md":"# CSS Support\n\n**Status: Experimental — API and behavior may change.**\n\nConfigure CSS handling including preprocessors, syntax lowering, minification, and code splitting.\n\n## Getting Started\n\nAll CSS support in `tsdown` is provided by the `@tsdown/css` package. Install it to enable CSS handling:\n\n```bash\nnpm install -D @tsdown/css\n```\n\nWhen `@tsdown/css` is installed, CSS processing is automatically enabled. Without it, encountering CSS files will result in an error.\n\n## CSS Import\n\nImport `.css` files from TypeScript/JavaScript — CSS is extracted into separate `.css` assets:\n\n```ts\n// src/index.ts\nimport './style.css'\nexport function greet() { return 'Hello' }\n```\n\nOutput: `index.mjs` + `index.css`\n\n### `@import` Inlining\n\nCSS `@import` statements are resolved and inlined automatically. No separate output files produced.\n\n### Inline CSS (`?inline`)\n\nAppend `?inline` to return processed CSS as a JS string instead of emitting a `.css` file:\n\n```ts\nimport './style.css' // → .css file\nimport css from './theme.css?inline' // → JS string\n```\n\nWorks with preprocessors too (`./foo.scss?inline`). Goes through full pipeline (preprocessors, @import inlining, lowering, minification). Tree-shakeable (`moduleSideEffects: false`).\n\n## CSS Pre-processors\n\nBuilt-in support for Sass, Less, and Stylus. Install the preprocessor:\n\n```bash\n# Sass (either one)\nnpm install -D sass-embedded # recommended, faster\nnpm install -D sass\n\n# Less\nnpm install -D less\n\n# Stylus\nnpm install -D stylus\n```\n\nThen import directly:\n\n```ts\nimport './style.scss'\nimport './theme.less'\nimport './global.styl'\n```\n\n### Preprocessor Options\n\n```ts\nexport default defineConfig({\n css: {\n preprocessorOptions: {\n scss: {\n additionalData: `$brand-color: #ff7e17;`,\n },\n less: {\n math: 'always',\n },\n stylus: {\n define: { '$brand-color': '#ff7e17' },\n },\n },\n },\n})\n```\n\n### `additionalData`\n\nInject code at the beginning of every preprocessor file:\n\n```ts\n// String form\nscss: {\n additionalData: `@use \"src/styles/variables\" as *;`,\n}\n\n// Function form\nscss: {\n additionalData: (source, filename) => {\n if (filename.includes('theme')) return source\n return `@use \"src/styles/variables\" as *;\\n${source}`\n },\n}\n```\n\n## CSS Minification\n\n```ts\nexport default defineConfig({\n css: {\n minify: true,\n },\n})\n```\n\nPowered by Lightning CSS.\n\n## CSS Target\n\nOverride the top-level `target` specifically for CSS:\n\n```ts\nexport default defineConfig({\n target: 'node18',\n css: {\n target: 'chrome90', // CSS-specific target\n },\n})\n```\n\nSet `css.target: false` to disable CSS syntax lowering entirely.\n\n## CSS Transformer\n\n`css.transformer` controls mutually exclusive CSS processing paths:\n\n- `'lightningcss'` (default): `@import` via Lightning CSS `bundleAsync()`, no PostCSS.\n- `'postcss'`: `@import` via `postcss-import`, PostCSS plugins applied, Lightning CSS for final transform only.\n\n```ts\nexport default defineConfig({\n css: {\n transformer: 'postcss',\n },\n})\n```\n\n### PostCSS Options\n\n```ts\nexport default defineConfig({\n css: {\n transformer: 'postcss',\n postcss: {\n plugins: [require('autoprefixer')],\n },\n // Or: postcss: './config' — path to search for postcss.config.js\n },\n})\n```\n\nAuto-detects PostCSS config from project root when `transformer` is `'postcss'` and `css.postcss` is omitted.\n\n## Lightning CSS (Syntax Lowering)\n\nInstall `lightningcss` to enable CSS syntax lowering based on your `target`:\n\n```bash\nnpm install -D lightningcss\n```\n\nWhen `target` is set (e.g., `target: 'chrome108'`), modern CSS features are automatically downleveled:\n\n```css\n/* Input */\n.foo { & .bar { color: red } }\n\n/* Output (chrome108) */\n.foo .bar { color: red }\n```\n\n### Custom Lightning CSS Options\n\n```ts\nimport { Features } from 'lightningcss'\n\nexport default defineConfig({\n css: {\n lightningcss: {\n targets: { chrome: 100 << 16 },\n include: Features.Nesting,\n },\n },\n})\n```\n\n`css.lightningcss.targets` takes precedence over both `target` and `css.target` for CSS.\n\n## CSS Modules\n\nFiles with `.module.css` (and `.module.scss`, `.module.less`, etc.) are treated as CSS modules — class names are scoped and exported as JS:\n\n```ts\nimport styles from './app.module.css'\nconsole.log(styles.title) // \"scoped_title_hash\"\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n css: {\n modules: {\n scopeBehaviour: 'local', // 'local' (default) | 'global'\n generateScopedName: '[hash]_[local]', // Lightning CSS pattern string\n localsConvention: 'camelCase', // 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly'\n },\n },\n})\n```\n\nSet `css.modules: false` to disable. Function-form `generateScopedName` requires `transformer: 'postcss'`.\n\n`localsConvention` also accepts a function compatible with Vite and\n`postcss-modules`:\n\n```ts\nexport default defineConfig({\n css: {\n modules: {\n localsConvention: (\n originalClassName,\n generatedClassName,\n inputFile,\n ) => originalClassName.replaceAll(/-([a-z0-9])/g, (_, c) => c.toUpperCase()),\n },\n },\n})\n```\n\nThe function form works with both CSS transformers and returns the JavaScript\nexport key.\n\n### Optional Dependencies (PostCSS path)\n\n```bash\nnpm install -D postcss postcss-modules\n```\n\n## Code Splitting\n\n### Merged (Default)\n\nAll CSS merged into a single file (default: `style.css`).\n\n```ts\nexport default defineConfig({\n css: {\n fileName: 'my-library.css', // Custom name (default: 'style.css')\n },\n})\n```\n\n### Per-Chunk Splitting\n\n```ts\nexport default defineConfig({\n css: {\n splitting: true, // Each JS chunk gets a corresponding .css file\n },\n})\n```\n\n## Preserving CSS Imports (`css.inject`)\n\nWhen enabled, JS output preserves `import` statements pointing to emitted CSS files. Consumers auto-import CSS alongside JS:\n\n```ts\nexport default defineConfig({\n css: {\n inject: true,\n },\n})\n```\n\n## PostCSS Optional Peer Dependencies\n\nWhen using `transformer: 'postcss'`, install these as needed:\n\n| Package | Purpose | Required When |\n|---------|---------|---------------|\n| `postcss` | Core PostCSS engine | Always (with `transformer: 'postcss'`) |\n| `postcss-import` | Resolve/inline `@import` | CSS uses `@import` |\n| `postcss-modules` | CSS modules (scoped classes) | Using `.module.css` files |\n\n```bash\nnpm install -D postcss postcss-import postcss-modules\n```\n\nAll declared as optional peer dependencies of `@tsdown/css`.\n\n## Options Reference\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `css.transformer` | `'postcss' \\| 'lightningcss'` | `'lightningcss'` | CSS processing pipeline |\n| `css.splitting` | `boolean` | `false` | Per-chunk CSS splitting |\n| `css.fileName` | `string` | `'style.css'` | Merged CSS file name |\n| `css.minify` | `boolean` | `false` | CSS minification |\n| `css.modules` | `object \\| false` | `{}` | CSS modules config, or `false` to disable |\n| `css.inject` | `boolean` | `false` | Preserve CSS imports in JS output |\n| `css.target` | `string \\| string[] \\| false` | _from `target`_ | CSS-specific lowering target |\n| `css.postcss` | `string \\| object` | — | PostCSS config path or inline options |\n| `css.preprocessorOptions` | `object` | — | Preprocessor options |\n| `css.lightningcss` | `object` | — | Lightning CSS options |\n\n## Related\n\n- [Target](option-target.md) - Configure syntax lowering targets\n- [Output Format](option-output-format.md) - Module output formats\n",".agents/skills/tsdown/references/option-dependencies.md":"# Dependencies\n\nControl how dependencies are bundled or externalized.\n\n## Overview\n\ntsdown intelligently handles dependencies to keep your library lightweight while ensuring all necessary code is included.\n\n## Default Behavior\n\n### Auto-Externalized\n\nThese are **NOT bundled** by default:\n\n- **`dependencies`** - Installed automatically with your package\n- **`peerDependencies`** - User must install manually\n- **`optionalDependencies`** - May or may not be installed depending on platform/config\n\n### Conditionally Bundled\n\nThese are **bundled ONLY if imported**:\n\n- **`devDependencies`** - Only if actually used in source code\n- **Phantom dependencies** - In node_modules but not in package.json\n\n## Configuration Options\n\nAll dependency options are grouped under the `deps` field:\n\n```ts\nexport default defineConfig({\n deps: {\n neverBundle: ['react', /^@myorg\\//],\n alwaysBundle: ['some-package'],\n onlyBundle: ['cac', 'bumpp'],\n onlyImport: ['cac'],\n resolveDepSubpath: true,\n },\n})\n```\n\n### `deps.neverBundle`\n\nMark dependencies as external (not bundled):\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: [\n 'react', // Single package\n 'react-dom',\n /^@myorg\\//, // Regex pattern (all @myorg/* packages)\n /^lodash/, // All lodash packages\n ],\n },\n})\n```\n\nSet to `true` to externalize ALL dependencies:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: true,\n },\n})\n```\n\n**Result:** Every import that follows npm package naming conventions is externalized as written, without being resolved. This is fast and even works when dependencies are not installed. Subpaths like `my-dep/utils` are preserved exactly unless `resolveDepSubpath` is enabled. Other non-relative imports (`#` subpath imports, path aliases like `~/`) are resolved: they stay external if they resolve into node_modules, and are bundled if they map to local files. Combine with `alwaysBundle` to bundle selected dependencies.\n\n### `deps.alwaysBundle`\n\nForce dependencies to be bundled:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n alwaysBundle: [\n 'some-package', // Bundle this even if in dependencies\n 'vendor-lib',\n ],\n },\n})\n```\n\n### `deps.onlyBundle`\n\nWhitelist of dependencies allowed to be bundled from node_modules. Throws an error if any unlisted dependency is bundled:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n onlyBundle: [\n 'cac', // Allow bundling cac\n 'bumpp', // Allow bundling bumpp\n /^my-utils/, // Regex patterns supported\n ],\n },\n})\n```\n\n**Behavior:**\n- **Array** (`['cac', /^my-/]`): Only matching dependencies can be bundled. Error for others.\n- **`false`**: Suppress all warnings about bundled dependencies.\n- **Not set** (default): Warns if any node_modules dependencies are bundled.\n\n**Note:** Include all sub-dependencies in the list, not just top-level imports.\n\n### `deps.onlyImport`\n\nWhitelist of packages the emitted output is allowed to import at runtime. Throws an error (listing all violations) if any chunk imports an unlisted package:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n onlyImport: [\n 'cac', // Also covers subpath imports like cac/deno\n /^my-utils/, // Regex patterns match the package name\n ],\n },\n})\n```\n\n**Behavior:**\n- Matching is based on the package name; subpath imports (`cac/deno`) match `cac`.\n- Node.js built-in modules are always allowed when `platform` is `node`.\n- Relative imports between code-split chunks are always allowed.\n- Declaration output (`.d.ts`) is checked too.\n\n**Limitation:** ES imports and dynamic `import()` expressions are checked. CJS `require()` calls are not detected.\n\n### `deps.resolveDepSubpath`\n\nBy default, tsdown preserves external dependency subpath imports as written. Enable `resolveDepSubpath` to resolve subpath imports to their actual package-relative paths when a package has no `exports` field. For example, `my-dep/functions/lt` may become `my-dep/functions/lt.js`, and `my-dep/folder` may become `my-dep/folder/index.js`.\n\n```ts\nexport default defineConfig({\n deps: {\n resolveDepSubpath: true, // default: false\n },\n})\n```\n\n## Common Patterns\n\n### React Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.tsx'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n 'react',\n 'react-dom',\n /^react\\//, // react/jsx-runtime, etc.\n ],\n },\n dts: true,\n})\n```\n\n### Utility Library with Shared Deps\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n alwaysBundle: ['lodash-es'],\n },\n dts: true,\n})\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n /^@mycompany\\//, // Don't bundle other workspace packages\n ],\n },\n dts: true,\n})\n```\n\n### CLI Tool (Bundle Everything)\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n format: ['esm'],\n platform: 'node',\n deps: {\n alwaysBundle: [/.*/],\n },\n shims: true,\n})\n```\n\n### Library with Specific Externals\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n 'vue',\n '@vue/runtime-core',\n '@vue/reactivity',\n ],\n },\n dts: true,\n})\n```\n\n## Declaration Files\n\nDependency handling for `.d.ts` files follows the same rules as JavaScript.\n\n### Complex Type Resolution\n\nUse TypeScript resolver for complex third-party types:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n dts: {\n resolver: 'tsc', // Use TypeScript resolver instead of Oxc\n },\n})\n```\n\n**When to use `tsc` resolver:**\n- Types in `@types/*` packages with non-standard naming (e.g., `@types/babel__generator`)\n- Complex type dependencies\n- Issues with default Oxc resolver\n\n**Trade-off:** `tsc` is slower but more compatible.\n\n## CLI Usage\n\n### Never Bundle\n\n```bash\ntsdown --deps.never-bundle react --deps.never-bundle react-dom\ntsdown --deps.never-bundle '/^@myorg\\/.*/'\n```\n\n## Migration from Deprecated Options\n\n| Deprecated Option | New Option |\n|---|---|\n| `external` | `deps.neverBundle` |\n| `noExternal` | `deps.alwaysBundle` |\n\n## Examples by Use Case\n\n### Framework Component\n\n```ts\n// Don't bundle framework\nexport default defineConfig({\n deps: {\n neverBundle: ['vue', 'react', 'solid-js', 'svelte'],\n },\n})\n```\n\n### Standalone App\n\n```ts\n// Bundle everything\nexport default defineConfig({\n deps: {\n alwaysBundle: [/.*/],\n },\n})\n```\n\n### Shared Library\n\n```ts\n// Bundle only specific utils\nexport default defineConfig({\n deps: {\n neverBundle: [/.*/], // External by default\n alwaysBundle: ['tiny-utils'], // Except this one\n },\n})\n```\n\n### Monorepo Package\n\n```ts\n// External workspace packages, bundle utilities\nexport default defineConfig({\n deps: {\n neverBundle: [\n /^@workspace\\//, // Other workspace packages\n 'react',\n 'react-dom',\n ],\n alwaysBundle: [\n 'lodash-es', // Bundle utility libraries\n ],\n },\n})\n```\n\n## Troubleshooting\n\n### Dependency Bundled Unexpectedly\n\nCheck if it's in `devDependencies` and imported. Move to `dependencies`:\n\n```json\n{\n \"dependencies\": {\n \"should-be-external\": \"^1.0.0\"\n }\n}\n```\n\nOr explicitly externalize:\n\n```ts\nexport default defineConfig({\n deps: {\n neverBundle: ['should-be-external'],\n },\n})\n```\n\n### Missing Dependency at Runtime\n\nEnsure it's in `dependencies`, `peerDependencies`, or `optionalDependencies`:\n\n```json\n{\n \"dependencies\": {\n \"needed-package\": \"^1.0.0\"\n }\n}\n```\n\nOr bundle it:\n\n```ts\nexport default defineConfig({\n deps: {\n alwaysBundle: ['needed-package'],\n },\n})\n```\n\n### Type Resolution Errors\n\nUse TypeScript resolver for complex types:\n\n```ts\nexport default defineConfig({\n dts: {\n resolver: 'tsc',\n },\n})\n```\n\n## Summary\n\n**Default behavior:**\n- `dependencies`, `peerDependencies`, & `optionalDependencies` → External\n- `devDependencies` & phantom deps → Bundled if imported\n\n**Override (under `deps`):**\n- `neverBundle` → Force external\n- `alwaysBundle` → Force bundled\n- `onlyBundle` → Whitelist bundled deps\n- `onlyImport` → Whitelist runtime imports in output\n- `neverBundle: true` → Externalize all dependencies\n- `resolveDepSubpath: true` → Resolve external dependency subpath imports to package-relative paths\n\n**Declaration files:**\n- Same bundling logic as JavaScript\n- Use `resolver: 'tsc'` for complex types\n\n## Tips\n\n1. **Keep dependencies external** for libraries\n2. **Bundle everything** for standalone CLIs\n3. **Use regex patterns** for namespaced packages\n4. **Check bundle size** to verify external/bundled split\n5. **Test with fresh install** to catch missing dependencies\n6. **Use tsc resolver** only when needed (slower)\n\n## Related Options\n\n- [External](option-dependencies.md) - This page\n- [Platform](option-platform.md) - Runtime environment\n- [Output Format](option-output-format.md) - Module formats\n- [DTS](option-dts.md) - Type declarations\n",".agents/skills/tsdown/references/option-dts.md":"# TypeScript Declaration Files\n\nGenerate `.d.ts` type declaration files for your library.\n\n## Overview\n\ntsdown uses [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts) to generate and bundle TypeScript declaration files.\n\n**Requirements:**\n- TypeScript must be installed in your project\n\n## Enabling DTS Generation\n\n### Auto-Enabled\n\nDTS generation is **automatically enabled** if `package.json` contains:\n- `types` field, or\n- `typings` field\n\n### Manual Enable\n\n#### CLI\n\n```bash\ntsdown --dts\n```\n\n#### Config File\n\n```ts\nexport default defineConfig({\n dts: true,\n})\n```\n\n## Performance\n\n### With `isolatedDeclarations` (Recommended)\n\n**Extremely fast** - uses oxc-transform for generation.\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"isolatedDeclarations\": true\n }\n}\n```\n\n### Without `isolatedDeclarations`\n\nFalls back to TypeScript compiler. Reliable but slower.\n\n## Declaration Maps\n\nMap `.d.ts` files back to original `.ts` sources (useful for monorepos).\n\n### Enable in tsconfig.json\n\n```json\n{\n \"compilerOptions\": {\n \"declarationMap\": true\n }\n}\n```\n\n### Enable in tsdown Config\n\n```ts\nexport default defineConfig({\n dts: {\n sourcemap: true,\n },\n})\n```\n\n## Advanced Options\n\n### Custom Compiler Options\n\nOverride TypeScript compiler options:\n\n```ts\nexport default defineConfig({\n dts: {\n compilerOptions: {\n removeComments: false,\n },\n },\n})\n```\n\n## Build Process\n\n- **ESM format**: `.js` and `.d.ts` files generated in same build\n- **CJS format**: Separate build process for `.d.ts` files\n\n## Common Patterns\n\n### Basic Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nOutput:\n- `dist/index.mjs`\n- `dist/index.cjs`\n- `dist/index.d.ts`\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nOutput:\n- `dist/index.mjs`, `dist/index.cjs`, `dist/index.d.ts`\n- `dist/utils.mjs`, `dist/utils.cjs`, `dist/utils.d.ts`\n\n### With Monorepo Support\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: {\n sourcemap: true, // Enable declaration maps\n },\n})\n```\n\n### Fast Build (Isolated Declarations)\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"isolatedDeclarations\": true,\n \"declaration\": true,\n \"declarationMap\": true\n }\n}\n```\n\n```ts\n// tsdown.config.ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true, // Will use fast oxc-transform\n})\n```\n\n## Troubleshooting\n\n### Missing Types\n\nEnsure TypeScript is installed:\n\n```bash\npnpm add -D typescript\n```\n\n### Slow Generation\n\nEnable `isolatedDeclarations` in `tsconfig.json` for faster builds.\n\n### Declaration Errors\n\nCheck that all exports have explicit types (required for `isolatedDeclarations`).\n\n### Report Issues\n\nFor DTS-specific issues, report to [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts/issues).\n\n### Vue Support\n\nEnable Vue component type generation (requires `vue-tsc`):\n\n```ts\nexport default defineConfig({\n dts: {\n vue: true,\n },\n})\n```\n\n### Oxc Transform\n\nControl Oxc usage for declaration generation:\n\n```ts\nexport default defineConfig({\n dts: {\n oxc: true, // Use oxc-transform (fast, requires isolatedDeclarations)\n },\n})\n```\n\n### Custom TSConfig\n\nSpecify a different tsconfig for DTS generation:\n\n```ts\nexport default defineConfig({\n dts: {\n tsconfig: './tsconfig.build.json',\n },\n})\n```\n\n## Available DTS Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `sourcemap` | `boolean` | Generate declaration source maps |\n| `compilerOptions` | `object` | Override TypeScript compiler options |\n| `vue` | `boolean` | Enable Vue type generation (requires vue-tsc) |\n| `oxc` | `boolean` | Use oxc-transform for fast generation |\n| `tsconfig` | `string` | Path to tsconfig file |\n| `resolver` | `'oxc' \\| 'tsc'` | Module resolver: `'oxc'` (default, fast) or `'tsc'` (more compatible) |\n| `cjsDefault` | `boolean` | CJS default export handling |\n| `sideEffects` | `boolean` | Preserve side effects in declarations |\n\n## Tips\n\n1. **Always enable DTS** for TypeScript libraries\n2. **Use isolatedDeclarations** for fast builds\n3. **Enable declaration maps** in monorepos\n4. **Ensure explicit types** for all exports\n5. **Install TypeScript** as dev dependency\n\n## Related Options\n\n- [Entry](option-entry.md) - Configure entry points\n- [Output Format](option-output-format.md) - Multiple output formats\n- [Target](option-target.md) - JavaScript version\n",".agents/skills/tsdown/references/option-entry.md":"# Entry Points\n\nConfigure which files to bundle as entry points.\n\n## Overview\n\nEntry points are the starting files for the bundling process. Each entry point generates a separate bundle.\n\n## Usage Patterns\n\n### CLI\n\n```bash\n# Single entry\ntsdown src/index.ts\n\n# Multiple entries\ntsdown src/index.ts src/cli.ts\n\n# Glob patterns\ntsdown 'src/*.ts'\n```\n\n### Config File\n\n#### Single Entry\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n})\n```\n\n#### Multiple Entries (Array)\n\n```ts\nexport default defineConfig({\n entry: ['src/entry1.ts', 'src/entry2.ts'],\n})\n```\n\n#### Named Entries (Object)\n\n```ts\nexport default defineConfig({\n entry: {\n main: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n})\n```\n\nOutput files will match the keys:\n- `dist/main.mjs`\n- `dist/utils.mjs`\n- `dist/cli.mjs`\n\n## Glob Patterns\n\nMatch multiple files dynamically using glob patterns:\n\n### All TypeScript Files\n\n```ts\nexport default defineConfig({\n entry: 'src/**/*.ts',\n})\n```\n\n### Exclude Test Files\n\n```ts\nexport default defineConfig({\n entry: ['src/*.ts', '!src/*.test.ts'],\n})\n```\n\n### Object Entries with Glob Patterns\n\nUse glob wildcards (`*`) in both keys and values. The `*` in the key acts as a placeholder replaced with the matched file name (without extension):\n\n```ts\nexport default defineConfig({\n entry: {\n // Maps src/foo.ts → dist/lib/foo.js, src/bar.ts → dist/lib/bar.js\n 'lib/*': 'src/*.ts',\n },\n})\n```\n\n#### Negation Patterns in Object Entries\n\nValues can be an array with negation patterns (`!`):\n\n```ts\nexport default defineConfig({\n entry: {\n 'hooks/*': ['src/hooks/*.ts', '!src/hooks/index.ts'],\n },\n})\n```\n\nMultiple positive and negation patterns:\n\n```ts\nexport default defineConfig({\n entry: {\n 'utils/*': [\n 'src/utils/*.ts',\n 'src/utils/*.tsx',\n '!src/utils/index.ts',\n '!src/utils/internal.ts',\n ],\n },\n})\n```\n\n**Warning:** Multiple positive patterns in an array value must share the same base directory.\n\n### Mixed Entries\n\nMix strings, glob patterns, and object entries in an array:\n\n```ts\nexport default defineConfig({\n entry: [\n 'src/*',\n '!src/foo.ts',\n { main: 'index.ts' },\n { 'lib/*': ['src/*.ts', '!src/bar.ts'] },\n ],\n})\n```\n\nObject entries take precedence when output names conflict.\n\n### Windows Compatibility\n\nUse forward slashes `/` instead of backslashes `\\` on Windows:\n\n```ts\n// ✅ Correct\nentry: 'src/utils/*.ts'\n\n// ❌ Wrong on Windows\nentry: 'src\\\\utils\\\\*.ts'\n```\n\n## Common Patterns\n\n### Library with Main Export\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### Library with Multiple Exports\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n client: 'src/client.ts',\n server: 'src/server.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### CLI Tool\n\n```ts\nexport default defineConfig({\n entry: {\n cli: 'src/cli.ts',\n },\n format: ['esm'],\n platform: 'node',\n})\n```\n\n### Preserve Directory Structure\n\nUse with `unbundle: true` to keep file structure:\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n unbundle: true,\n format: ['esm'],\n dts: true,\n})\n```\n\nThis will output files matching the source structure:\n- `src/index.ts` → `dist/index.mjs`\n- `src/utils/helper.ts` → `dist/utils/helper.mjs`\n\n## Tips\n\n1. **Use glob patterns** for multiple related files\n2. **Use object syntax** for custom output names\n3. **Exclude test files** with negation patterns `!**/*.test.ts`\n4. **Combine with unbundle** to preserve directory structure\n5. **Use named entries** for better control over output filenames\n",".agents/skills/tsdown/references/option-exe.md":"# Executable - `exe`\n\n**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html).\n\n## Requirements\n\n- Node.js >= 25.7.0\n- Not supported in Bun or Deno\n\n## Basic Usage\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: true,\n})\n```\n\n## Behavior When Enabled\n\n- Declaration file generation (`dts`) is disabled by default\n- Code splitting is disabled\n- Only single entry points are supported\n- Legacy CJS warnings are suppressed\n\n## Advanced Configuration\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n fileName: 'my-tool',\n seaConfig: {\n disableExperimentalSEAWarning: true,\n useCodeCache: true,\n useSnapshot: false,\n },\n },\n})\n```\n\n## `ExeOptions`\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `seaConfig` | `Omit` | Node.js configuration options |\n| `fileName` | `string \\| ((chunk) => string)` | Custom output file name (without `.exe` or platform suffixes) |\n| `targets` | `ExeTarget[]` | Cross-platform build targets (requires `@tsdown/exe`) |\n\n## `SeaConfig`\n\nSee [Node.js Single Executable Applications documentation](https://nodejs.org/api/single-executable-applications.html).\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `disableExperimentalSEAWarning` | `boolean` | `true` | Disable the experimental warning |\n| `useSnapshot` | `boolean` | `false` | Use V8 snapshot |\n| `useCodeCache` | `boolean` | `false` | Use V8 code cache |\n| `execArgv` | `string[]` | - | Extra Node.js arguments |\n| `execArgvExtension` | `'none' \\| 'env' \\| 'cli'` | `'env'` | How to extend execArgv |\n| `assets` | `Record` | - | Assets to embed |\n\n## Cross-Platform Builds\n\nInstall `@tsdown/exe` to build executables for multiple platforms from a single machine:\n\n```bash\npnpm add -D @tsdown/exe\n```\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [\n { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },\n { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },\n { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },\n ],\n },\n})\n```\n\nThis downloads the target platform's Node.js binary, caches it locally, and produces platform-suffixed output:\n\n```\ndist/\n cli-linux-x64\n cli-darwin-arm64\n cli-win-x64.exe\n```\n\n### `ExeTarget`\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `platform` | `'win' \\| 'darwin' \\| 'linux'` | Target OS (nodejs.org naming) |\n| `arch` | `'x64' \\| 'arm64'` | Target CPU architecture |\n| `nodeVersion` | `string` | Node.js version (must be `>=25.7.0`), or `'latest'` / `'latest-lts'` to resolve automatically |\n\n### Custom Node.js Index and Download URL\n\nWhen downloading Node.js binaries (e.g. behind a corporate proxy or using a mirror), you can customize the sources:\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [{ platform: 'linux', arch: 'x64', nodeVersion: 'latest-lts' }],\n // Index used to resolve 'latest' / 'latest-lts' versions\n nodeDistIndexUrl: 'https://mirrors.example.com/node/index.json', // default: https://nodejs.org/dist/index.json\n // Fully custom download URL per target\n getDownloadUrl: (target) =>\n `https://mirrors.example.com/node/v${target.nodeVersion}/node-v${target.nodeVersion}-${target.platform}-${target.arch}.tar.gz`,\n },\n})\n```\n\n### Caching\n\nDownloaded Node.js binaries are cached in system cache directories:\n- **macOS:** `~/Library/Caches/tsdown/node/`\n- **Linux:** `~/.cache/tsdown/node/`\n- **Windows:** `%LOCALAPPDATA%/tsdown/Caches/node/`\n\n## Platform Notes\n\n- On macOS, the executable is automatically codesigned (ad-hoc) for Gatekeeper compatibility\n- On Windows, the `.exe` extension is automatically appended\n- When `targets` is specified, `seaConfig.executable` is ignored\n\n## CLI\n\n```bash\ntsdown --exe\ntsdown src/cli.ts --exe\n```\n",".agents/skills/tsdown/references/option-lint.md":"# Package Validation (publint & attw)\n\nValidate your package configuration and type declarations before publishing.\n\n## Overview\n\ntsdown integrates with [publint](https://publint.dev/) and [Are the types wrong?](https://arethetypeswrong.github.io/) (attw) to catch common packaging issues. Both are optional dependencies.\n\n## Installation\n\n```bash\n# publint only\nnpm install -D publint\n\n# attw only\nnpm install -D @arethetypeswrong/core\n\n# both\nnpm install -D publint @arethetypeswrong/core\n```\n\n## publint\n\nChecks that `package.json` fields (`exports`, `main`, `module`, `types`) match your actual output files.\n\n### Enable\n\n```ts\nexport default defineConfig({\n publint: true,\n})\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n publint: {\n level: 'error', // 'warning' | 'error' | 'suggestion'\n },\n})\n```\n\n### CLI\n\n```bash\ntsdown --publint\n```\n\n## attw (Are the types wrong?)\n\nVerifies TypeScript declarations are correct across different module resolution strategies (`node10`, `node16`, `bundler`).\n\n### Enable\n\n```ts\nexport default defineConfig({\n attw: true,\n})\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n attw: {\n profile: 'node16', // 'strict' | 'node16' | 'esm-only'\n level: 'error', // 'warn' | 'error'\n ignoreRules: ['false-cjs', 'cjs-resolves-to-esm'],\n },\n})\n```\n\n### Profiles\n\n| Profile | Description |\n|---------|-------------|\n| `strict` | Requires all resolutions to pass (default) |\n| `node16` | Ignores `node10` resolution failures |\n| `esm-only` | Ignores `node10` and `node16-cjs` resolution failures |\n\n### Ignore Rules\n\nSuppress specific problem types with `ignoreRules`:\n\n| Rule | Description |\n|------|-------------|\n| `no-resolution` | Module could not be resolved |\n| `untyped-resolution` | Resolution succeeded but has no types |\n| `false-cjs` | Types indicate CJS but implementation is ESM |\n| `false-esm` | Types indicate ESM but implementation is CJS |\n| `cjs-resolves-to-esm` | CJS resolution points to an ESM module |\n| `fallback-condition` | A fallback/wildcard condition was used |\n| `cjs-only-exports-default` | CJS module only exports a default |\n| `named-exports` | Named exports mismatch between types and implementation |\n| `false-export-default` | Types declare a default export that doesn't exist |\n| `missing-export-equals` | Types are missing `export =` for CJS |\n| `unexpected-module-syntax` | File uses unexpected module syntax |\n| `internal-resolution-error` | Internal resolution error in type checking |\n\n### CLI\n\n```bash\ntsdown --attw\n```\n\n## CI Integration\n\nBoth tools support CI-aware options:\n\n```ts\nexport default defineConfig({\n publint: 'ci-only',\n attw: {\n enabled: 'ci-only',\n profile: 'node16',\n level: 'error',\n },\n})\n```\n\nBoth tools require a `package.json` in your project directory.\n\n## Related Options\n\n- [CI Environment](advanced-ci.md) - CI-aware option details\n- [Package Exports](option-package-exports.md) - Generate exports field\n",".agents/skills/tsdown/references/option-log-level.md":"# Log Level\n\nControl the verbosity of build output.\n\n## Overview\n\nThe `logLevel` option controls how much information tsdown displays during the build process.\n\n## Type\n\n```ts\nlogLevel?: 'silent' | 'error' | 'warn' | 'info'\n```\n\n**Default:** `'info'`\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Suppress all output\ntsdown --log-level silent\n\n# Only show errors\ntsdown --log-level error\n\n# Show warnings and errors\ntsdown --log-level warn\n\n# Show all info (default)\ntsdown --log-level info\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'error',\n})\n```\n\n## Available Levels\n\n| Level | Shows | Use Case |\n|-------|-------|----------|\n| `silent` | Nothing | CI/CD pipelines, scripting |\n| `error` | Errors only | Minimal output |\n| `warn` | Warnings + errors | Standard CI/CD |\n| `info` | All messages | Development (default) |\n\n## Common Patterns\n\n### CI/CD Pipeline\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'error', // Only show errors in CI\n})\n```\n\n### Scripting\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'silent', // No output for automation\n})\n```\n\n## Fail on Warnings\n\nThe `failOnWarn` option controls whether warnings cause the build to exit with a non-zero code. Defaults to `false` — warnings never fail the build.\n\n```ts\nexport default defineConfig({\n failOnWarn: false, // Default: never fail on warnings\n // failOnWarn: true, // Always fail on warnings\n // failOnWarn: 'ci-only', // Fail on warnings only in CI\n})\n```\n\nSee [CI Environment](advanced-ci.md) for more about CI-aware options.\n\n## Suppressing Warnings\n\nThe `suppressWarnings` option silences warnings whose message matches a given pattern. This is useful for opting out of non-actionable notices (such as the TypeScript 7.0 experimental API warning) while keeping other warnings visible.\n\n### Type\n\n```ts\nsuppressWarnings?:\n | string\n | RegExp\n | Array\n | ((msg: string) => boolean)\n```\n\n- **string** – substring match\n- **RegExp** – regular expression match\n- **array** – matches if any entry matches\n- **function** – custom predicate\n\n### Usage\n\n```ts\nexport default defineConfig({\n suppressWarnings: [\n 'is experimental', // substring match\n /Circular dependency/, // regexp match\n ],\n // Or a predicate function:\n // suppressWarnings: (msg) => msg.includes('is experimental'),\n})\n```\n\nMatched warnings are dropped **before** `failOnWarn` is applied, so a suppressed warning will not fail the build even when `failOnWarn: true`.\n\n## Related Options\n\n- [CI Environment](advanced-ci.md) - CI-aware option details\n- [CLI Reference](reference-cli.md) - All CLI options\n- [Config File](option-config-file.md) - Configuration setup\n",".agents/skills/tsdown/references/option-minification.md":"# Minification\n\nCompress code to reduce bundle size.\n\n## Overview\n\nMinification removes unnecessary characters (whitespace, comments) and optimizes code for production, reducing bundle size and improving load times.\n\n**Note:** Uses [Oxc minifier](https://oxc.rs/docs/contribute/minifier) internally. The minifier is currently in alpha.\n\n## Type\n\n```ts\nminify?: boolean | 'dce-only' | MinifyOptions\n```\n\n- `true` — Enable full minification (whitespace removal, mangling, compression)\n- `false` — Disable minification (default)\n- `'dce-only'` — Only perform dead code elimination without full minification\n- `MinifyOptions` — Pass detailed options to the Oxc minifier\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Enable minification\ntsdown --minify\n\n# Disable minification\ntsdown --no-minify\n```\n\n**Note:** The CLI `--minify` flag is a boolean toggle. For `'dce-only'` mode or advanced options, use the config file.\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n minify: true,\n})\n```\n\n### DCE-Only Mode\n\nRemove dead code without full minification (keeps readable output):\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n minify: 'dce-only',\n})\n```\n\n## Example Output\n\n### Without Minification\n\n```js\n// dist/index.mjs\nconst x = 1\n\nfunction hello(x$1) {\n console.log('Hello World')\n console.log(x$1)\n}\n\nhello(x)\n```\n\n### With Minification\n\n```js\n// dist/index.mjs\nconst e=1;function t(e){console.log(`Hello World`),console.log(e)}t(e);\n```\n\n## Common Patterns\n\n### Production Build\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: true,\n clean: true,\n})\n```\n\n### Conditional Minification\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: !options.watch, // Only minify in production\n}))\n```\n\n### Browser Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n minify: true,\n})\n```\n\n### Multiple Builds\n\n```ts\nexport default defineConfig([\n // Development build\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: false,\n outDir: 'dist/dev',\n },\n // Production build\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: true,\n outDir: 'dist/prod',\n },\n])\n```\n\n## CLI Examples\n\n```bash\n# Production build with minification\ntsdown --minify --clean\n\n# Multiple formats with minification\ntsdown --format esm --format cjs --minify\n\n# Conditional minification (only when not watching)\ntsdown --minify # Or omit --watch\n```\n\n## Tips\n\n1. **Use `minify: true`** for production builds\n2. **Use `'dce-only'`** to remove dead code while keeping output readable\n3. **Skip minification** during development for faster rebuilds\n4. **Combine with tree shaking** for best results\n5. **Test minified output** thoroughly (Oxc minifier is in alpha)\n\n## Troubleshooting\n\n### Minified Code Has Bugs\n\nOxc minifier is in alpha and may have issues:\n\n1. **Use DCE-only mode**: `minify: 'dce-only'`\n2. **Report bug** to [Oxc project](https://github.com/oxc-project/oxc/issues)\n3. **Disable minification**: `minify: false`\n\n### Unexpected Output\n\n- **Test unminified** first to isolate issue\n- **Check source maps** for debugging\n- **Verify target compatibility**\n\n## Related Options\n\n- [Tree Shaking](option-tree-shaking.md) - Remove unused code\n- [Target](option-target.md) - Syntax transformations\n- [Output Format](option-output-format.md) - Module formats\n- [Sourcemap](option-sourcemap.md) - Debug information\n",".agents/skills/tsdown/references/option-output-directory.md":"# Output Directory\n\nConfigure the output directory for bundled files.\n\n## Overview\n\nBy default, tsdown outputs bundled files to the `dist` directory. You can customize this location using the `outDir` option.\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Default output to dist/\ntsdown\n\n# Custom output directory\ntsdown --out-dir build\ntsdown -d lib\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: 'build',\n})\n```\n\n## Common Patterns\n\n### Standard Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist', // Default\n dts: true,\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n├── index.cjs\n└── index.d.ts\n```\n\n### Separate Directories by Format\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n outDir: 'dist/esm',\n },\n {\n entry: ['src/index.ts'],\n format: ['cjs'],\n outDir: 'dist/cjs',\n },\n])\n```\n\n**Output:**\n```\ndist/\n├── esm/\n│ └── index.js\n└── cjs/\n └── index.js\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: 'lib', // Custom directory\n clean: true,\n})\n```\n\n### Build to Root\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: '.', // Output to project root (not recommended)\n clean: false, // Don't clean root!\n})\n```\n\n**Warning:** Be careful when outputting to root to avoid deleting important files.\n\n## Output Extensions\n\n### Custom Extensions\n\nUse `outExtensions` to control file extensions:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n outExtensions({ format }) {\n return {\n js: format === 'esm' ? '.mjs' : '.cjs',\n }\n },\n})\n```\n\n### Default Extensions\n\n| Format | Default Extension | With `type: \"module\"` |\n|--------|-------------------|----------------------|\n| `esm` | `.mjs` | `.js` |\n| `cjs` | `.cjs` | `.js` |\n| `iife` | `.iife.js` | `.iife.js` |\n| `umd` | `.umd.js` | `.umd.js` |\n\nFor IIFE/UMD builds, `outExtensions` customizes extensions or suffixes but does not remove the built-in `.iife` or `.umd` segment. Use `outputOptions.entryFileNames` for custom full filename patterns.\n\n### ESM with .js Extension\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm'],\n outExtensions: () => ({ js: '.js' }),\n})\n```\n\nRequires `\"type\": \"module\"` in package.json.\n\n## File Naming\n\n### Entry Names\n\nControl output filenames based on entry names:\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n },\n outDir: 'dist',\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n└── utils.mjs\n```\n\n### Glob Entry\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n outDir: 'dist',\n unbundle: true, // Preserve structure\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n├── utils/\n│ └── helper.mjs\n└── components/\n └── button.mjs\n```\n\n## Multiple Builds\n\n### Same Output Directory\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true, // Clean first\n },\n {\n entry: ['src/cli.ts'],\n outDir: 'dist',\n clean: false, // Don't clean again\n },\n])\n```\n\n### Different Output Directories\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist/lib',\n },\n {\n entry: ['src/cli.ts'],\n format: ['esm'],\n outDir: 'dist/bin',\n },\n])\n```\n\n## CLI Examples\n\n```bash\n# Default\ntsdown\n\n# Custom directory\ntsdown --out-dir build\ntsdown -d lib\n\n# Nested directory\ntsdown --out-dir dist/lib\n\n# With other options\ntsdown --out-dir build --format esm,cjs --dts\n```\n\n## Tips\n\n1. **Use default `dist`** for standard projects\n2. **Be careful with root** - avoid `outDir: '.'`\n3. **Clean before build** - use `clean: true`\n4. **Consistent naming** - match your project conventions\n5. **Separate by format** if needed for clarity\n6. **Check .gitignore** - ensure output dir is ignored\n\n## Troubleshooting\n\n### Files Not in Expected Location\n\n- Check `outDir` config\n- Verify build completed successfully\n- Look for typos in path\n\n### Files Deleted Unexpectedly\n\n- Check if `clean: true`\n- Ensure outDir doesn't overlap with source\n- Don't use root as outDir\n\n### Permission Errors\n\n- Check write permissions\n- Ensure directory isn't locked\n- Try different location\n\n## Related Options\n\n- [Cleaning](option-cleaning.md) - Clean output directory\n- [Entry](option-entry.md) - Entry points\n- [Output Format](option-output-format.md) - Module formats\n- [Unbundle](option-unbundle.md) - Preserve structure\n",".agents/skills/tsdown/references/option-output-format.md":"# Output Format\n\nConfigure the module format(s) for generated bundles.\n\n## Overview\n\ntsdown can generate bundles in multiple formats. Default is ESM.\n\n## Available Formats\n\n| Format | Description | Use Case |\n|--------|-------------|----------|\n| `esm` | ECMAScript Module (default) | Modern Node.js, browsers, Deno |\n| `cjs` | CommonJS | Legacy Node.js, require() |\n| `iife` | Immediately Invoked Function Expression | Browser `\n\n\n\n\n```\n\n### Export Components\n\n```ts\n// src/index.ts\nexport { default as Button } from './Button.vue'\nexport { default as Input } from './Input.vue'\nexport { default as Modal } from './Modal.vue'\n\n// Re-export types\nexport type { ButtonProps } from './Button.vue'\n```\n\n## Common Patterns\n\n### Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n platform: 'neutral',\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [\n Vue({\n isProduction: true,\n style: {\n trim: true,\n },\n }),\n ],\n dts: {\n vue: true,\n },\n clean: true,\n})\n```\n\n### Multiple Components\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n Button: 'src/Button.vue',\n Input: 'src/Input.vue',\n Modal: 'src/Modal.vue',\n },\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [Vue({ isProduction: true })],\n dts: { vue: true },\n})\n```\n\n### With Composition Utilities\n\n```ts\n// src/composables/useCounter.ts\nimport { ref } from 'vue'\n\nexport function useCounter(initial = 0) {\n const count = ref(initial)\n const increment = () => count.value++\n const decrement = () => count.value--\n return { count, increment, decrement }\n}\n```\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [Vue({ isProduction: true })],\n dts: { vue: true },\n})\n```\n\n### TypeScript Configuration\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"ESNext\",\n \"lib\": [\"ES2020\", \"DOM\", \"DOM.Iterable\"],\n \"jsx\": \"preserve\",\n \"moduleResolution\": \"bundler\",\n \"allowImportingTsExtensions\": true,\n \"strict\": true,\n \"isolatedDeclarations\": true,\n \"skipLibCheck\": true\n },\n \"include\": [\"src\"],\n \"exclude\": [\"node_modules\", \"dist\"]\n}\n```\n\n### Package.json Configuration\n\n```json\n{\n \"name\": \"my-vue-library\",\n \"version\": \"1.0.0\",\n \"type\": \"module\",\n \"main\": \"./dist/index.cjs\",\n \"module\": \"./dist/index.mjs\",\n \"types\": \"./dist/index.d.ts\",\n \"exports\": {\n \".\": {\n \"types\": \"./dist/index.d.ts\",\n \"import\": \"./dist/index.mjs\",\n \"require\": \"./dist/index.cjs\"\n },\n },\n \"files\": [\"dist\"],\n \"peerDependencies\": {\n \"vue\": \"^3.0.0\"\n },\n \"devDependencies\": {\n \"tsdown\": \"^0.9.0\",\n \"typescript\": \"^5.0.0\",\n \"unplugin-vue\": \"^5.0.0\",\n \"vue\": \"^3.4.0\",\n \"vue-tsc\": \"^2.0.0\"\n }\n}\n```\n\n## Advanced Patterns\n\n### With Vite Plugins\n\nSome Vite Vue plugins may work:\n\n```ts\nimport Vue from 'unplugin-vue/rolldown'\nimport Components from 'unplugin-vue-components/rolldown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [\n Vue({ isProduction: true }),\n Components({\n dts: 'src/components.d.ts',\n }),\n ],\n dts: { vue: true },\n})\n```\n\n### JSX Support\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [\n Vue({\n isProduction: true,\n script: {\n propsDestructure: true,\n },\n }),\n ],\n inputOptions: {\n transform: {\n jsx: 'automatic',\n jsxImportSource: 'vue',\n },\n },\n dts: { vue: true },\n})\n```\n\n### Monorepo Vue Packages\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue', /^@mycompany\\//],\n },\n plugins: [Vue({ isProduction: true })],\n dts: { vue: true },\n})\n```\n\n## Plugin Options\n\n### unplugin-vue Options\n\n```ts\nVue({\n isProduction: true,\n script: {\n defineModel: true,\n propsDestructure: true,\n },\n style: {\n trim: true,\n },\n template: {\n compilerOptions: {\n isCustomElement: (tag) => tag.startsWith('custom-'),\n },\n },\n})\n```\n\n## Tips\n\n1. **Always externalize Vue** - Don't bundle Vue itself\n2. **Enable vue: true in dts** - For proper type generation\n3. **Use platform: 'neutral'** - Maximum compatibility\n4. **Install vue-tsc** - Required for type generation\n5. **Set isProduction: true** - Optimize for production\n6. **Add peer dependency** - Vue as peer dependency\n\n## Troubleshooting\n\n### Type Generation Fails\n\nEnsure vue-tsc is installed:\n```bash\npnpm add -D vue-tsc\n```\n\nEnable in config:\n```ts\ndts: { vue: true }\n```\n\n### Component Types Missing\n\nCheck TypeScript config:\n```json\n{\n \"compilerOptions\": {\n \"jsx\": \"preserve\",\n \"moduleResolution\": \"bundler\"\n }\n}\n```\n\n### Vue Not Externalized\n\nAdd to deps.neverBundle:\n```ts\ndeps: {\n neverBundle: ['vue'],\n}\n```\n\n### SFC Compilation Errors\n\nCheck unplugin-vue version:\n```bash\npnpm add -D unplugin-vue@latest\n```\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Dependencies](option-dependencies.md) - External packages\n- [DTS](option-dts.md) - Type declarations\n- [React Recipe](recipe-react.md) - React component libraries\n",".agents/skills/tsdown/references/recipe-wasm.md":"# WASM Support\n\nBundle WebAssembly modules in your TypeScript/JavaScript project.\n\n## Overview\n\ntsdown supports WASM through [`rolldown-plugin-wasm`](https://github.com/sxzz/rolldown-plugin-wasm), enabling direct `.wasm` imports with synchronous and asynchronous instantiation.\n\n## Setup\n\n### Install\n\n```bash\npnpm add -D rolldown-plugin-wasm\n```\n\n### Configure\n\n```ts\nimport { wasm } from 'rolldown-plugin-wasm'\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n plugins: [wasm()],\n})\n```\n\n### TypeScript Support\n\nAdd type declarations to `tsconfig.json`:\n\n```jsonc\n{\n \"compilerOptions\": {\n \"types\": [\"rolldown-plugin-wasm/types\"]\n }\n}\n```\n\n## Importing WASM Modules\n\n### Direct Import\n\n```ts\nimport { add } from './add.wasm'\nadd(1, 2)\n```\n\n### Async Init\n\nUse `?init` query for async initialization:\n\n```ts\nimport init from './add.wasm?init'\nconst instance = await init(imports) // imports optional\ninstance.exports.add(1, 2)\n```\n\n### Sync Init\n\nUse `?init&sync` query for synchronous initialization:\n\n```ts\nimport initSync from './add.wasm?init&sync'\nconst instance = initSync(imports) // imports optional\ninstance.exports.add(1, 2)\n```\n\n## wasm-bindgen Support\n\n### Target `bundler` (Recommended)\n\n```ts\nimport { add } from 'some-pkg'\nadd(1, 2)\n```\n\n### Target `web` (Node.js)\n\n```ts\nimport { readFile } from 'node:fs/promises'\nimport init, { add } from 'some-pkg'\nimport wasmUrl from 'some-pkg/add_bg.wasm?url'\n\nawait init({\n module_or_path: readFile(new URL(wasmUrl, import.meta.url)),\n})\nadd(1, 2)\n```\n\n### Target `web` (Browser)\n\n```ts\nimport init, { add } from 'some-pkg/add.js'\nimport wasmUrl from 'some-pkg/add_bg.wasm?url'\n\nawait init({ module_or_path: wasmUrl })\nadd(1, 2)\n```\n\n`nodejs` and `no-modules` wasm-bindgen targets are not supported.\n\n## Plugin Options\n\n```ts\nwasm({\n maxFileSize: 14 * 1024, // Max size for inline (default: 14KB)\n fileName: '[hash][extname]', // Output file name pattern\n targetEnv: 'auto', // 'auto' | 'auto-inline' | 'browser' | 'node'\n})\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `maxFileSize` | `14 * 1024` | Max file size for inlining. Set to `0` to always copy. |\n| `fileName` | `'[hash][extname]'` | Pattern for emitted WASM files |\n| `targetEnv` | `'auto'` | `'auto'` detects at runtime; `'browser'` omits Node builtins; `'node'` omits fetch |\n\n## Related Options\n\n- [Plugins](advanced-plugins.md) - Plugin system overview\n- [Platform](option-platform.md) - Target platform configuration\n",".agents/skills/tsdown/references/reference-cli.md":"# CLI Reference\n\nComplete reference for tsdown command-line interface.\n\n## Overview\n\nAll CLI flags can also be set in the config file. CLI flags override config file options.\n\n## Flag Patterns\n\nCLI flag mapping rules:\n- `--foo` sets `foo: true`\n- `--no-foo` sets `foo: false`\n- `--foo.bar` sets `foo: { bar: true }`\n- `--format esm --format cjs` sets `format: ['esm', 'cjs']`\n\nCLI flags support both camelCase and kebab-case. For example, `--outDir` and `--out-dir` are equivalent.\n\n## Basic Commands\n\n### Build\n\n```bash\n# Build with default config\ntsdown\n\n# Build specific files\ntsdown src/index.ts src/cli.ts\n\n# Build with watch mode\ntsdown --watch\n```\n\n## Configuration\n\n### `--config, -c `\n\nSpecify custom config file:\n\n```bash\ntsdown --config build.config.ts\ntsdown -c custom-config.js\n```\n\n### `--no-config`\n\nDisable config file loading:\n\n```bash\ntsdown --no-config src/index.ts\n```\n\n### `--config-loader `\n\nChoose config loader (`auto`, `native`, `tsx`, `unrun`). `tsx` and `unrun` are optional peer dependencies — install them manually first:\n\n```bash\ntsdown --config-loader tsx\ntsdown --config-loader unrun\n```\n\n### `--tsconfig `\n\nSpecify TypeScript config file:\n\n```bash\ntsdown --tsconfig tsconfig.build.json\n```\n\n## Entry Points\n\n### `[...files]`\n\nSpecify entry files as arguments:\n\n```bash\ntsdown src/index.ts src/utils.ts\n```\n\n## Output Options\n\n### `--format `\n\nOutput format (`esm`, `cjs`, `iife`, `umd`):\n\n```bash\ntsdown --format esm\ntsdown --format esm --format cjs\n```\n\n### `--out-dir, -d `\n\nOutput directory:\n\n```bash\ntsdown --out-dir lib\ntsdown -d dist\n```\n\n### `--dts`\n\nGenerate TypeScript declarations:\n\n```bash\ntsdown --dts\n```\n\n### `--clean`\n\nClean output directory before build:\n\n```bash\ntsdown --clean\n```\n\n## Build Options\n\n### `--target `\n\nJavaScript target version:\n\n```bash\ntsdown --target es2020\ntsdown --target node18\ntsdown --target chrome100\ntsdown --no-target # Disable transformations\n```\n\n### `--platform `\n\nTarget platform (`node`, `browser`, `neutral`):\n\n```bash\ntsdown --platform node\ntsdown --platform browser\n```\n\n### `--minify`\n\nEnable minification:\n\n```bash\ntsdown --minify\ntsdown --no-minify\n```\n\n### `--sourcemap`\n\nGenerate source maps:\n\n```bash\ntsdown --sourcemap\ntsdown --sourcemap inline\n```\n\n### `--treeshake`\n\nEnable/disable tree shaking:\n\n```bash\ntsdown --treeshake\ntsdown --no-treeshake\n```\n\n## Dependencies\n\n### `--deps.never-bundle `\n\nMark module as external (not bundled):\n\n```bash\ntsdown --deps.never-bundle react --deps.never-bundle react-dom\n```\n\n### `--shims`\n\nAdd ESM/CJS compatibility shims:\n\n```bash\ntsdown --shims\n```\n\n## Development\n\n### `--watch, -w [path]`\n\nEnable watch mode:\n\n```bash\ntsdown --watch\ntsdown -w\ntsdown --watch src # Watch specific directory\n```\n\n### `--ignore-watch `\n\nIgnore paths in watch mode:\n\n```bash\ntsdown --watch --ignore-watch test\n```\n\n### `--on-success `\n\nRun command after successful build:\n\n```bash\ntsdown --watch --on-success \"echo Build complete!\"\n```\n\n## Environment Variables\n\n### `--env.* `\n\nSet compile-time environment variables:\n\n```bash\ntsdown --env.NODE_ENV=production --env.API_URL=https://api.example.com\n```\n\nAccess as `import.meta.env.*` or `process.env.*`.\n\n### `--env-file `\n\nLoad environment variables from file:\n\n```bash\ntsdown --env-file .env.production\n```\n\n### `--env-prefix `\n\nFilter environment variables by prefix (default: `TSDOWN_`):\n\n```bash\ntsdown --env-file .env --env-prefix APP_ --env-prefix TSDOWN_\n```\n\n## Assets\n\n### `--copy `\n\nCopy directory to output:\n\n```bash\ntsdown --copy public\ntsdown --copy assets --copy static\n```\n\n## Executable\n\n### `--exe`\n\n**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html). Requires Node.js >= 25.7.0, not supported in Bun or Deno. Cross-platform builds supported via `@tsdown/exe`.\n\n```bash\ntsdown --exe\n```\n\nWhen enabled:\n- Declaration file generation (`dts`) is disabled by default\n- Code splitting is disabled\n- Only single entry points are supported\n\nSee [Executable](option-exe.md) for advanced configuration and cross-platform builds.\n\n## Package Management\n\n### `--exports`\n\nGenerate the `exports` field in package.json:\n\n```bash\ntsdown --exports\n```\n\n### `--publint`\n\nEnable package validation:\n\n```bash\ntsdown --publint\n```\n\n### `--attw`\n\nEnable \"Are the types wrong\" validation:\n\n```bash\ntsdown --attw\n```\n\n### `--unused`\n\nCheck for unused dependencies:\n\n```bash\ntsdown --unused\n```\n\n## Logging\n\n### `--log-level `\n\nSet logging verbosity (`silent`, `error`, `warn`, `info`):\n\n```bash\ntsdown --log-level error\ntsdown --log-level warn\n```\n\n### `--report` / `--no-report`\n\nEnable/disable build report:\n\n```bash\ntsdown --no-report # Disable size report\ntsdown --report # Enable (default)\n```\n\n### `--debug [feat]`\n\nShow debug logs:\n\n```bash\ntsdown --debug\ntsdown --debug rolldown # Debug specific feature\n```\n\n## Integration\n\n### `--from-vite [vitest]`\n\nExtend Vite or Vitest config:\n\n```bash\ntsdown --from-vite # Use vite.config.*\ntsdown --from-vite vitest # Use vitest.config.*\n```\n\n## Workspace / Monorepo\n\n### `--workspace, -W [dir]`\n\nEnable workspace mode for building multiple packages:\n\n```bash\ntsdown -W\ntsdown -W packages/\n```\n\n### `--filter, -F `\n\nFilter configs by name or working directory. Supports regex:\n\n```bash\ntsdown -W -F my-package\ntsdown -W -F /^pkg-/\n```\n\n### `--concurrency `\n\nMaximum number of Rolldown builds to run in parallel. Defaults to unlimited:\n\n```bash\ntsdown -W --concurrency 4\n```\n\nNot supported in watch mode (ignored with a warning).\n\n### `--unbundle`\n\nEnable unbundle (bundleless) mode:\n\n```bash\ntsdown --unbundle\n```\n\n### `--root `\n\nSpecify the root directory of input files (similar to TypeScript's `rootDir`). Controls the output directory structure by determining how entry file paths map to output paths. Defaults to the common base directory of all entry files.\n\n```bash\ntsdown --root src\ntsdown --root .\n```\n\n### `--fail-on-warn`\n\nFail on warnings (enabled by default):\n\n```bash\ntsdown --no-fail-on-warn # Disable\n```\n\n## Common Usage Patterns\n\n### Basic Build\n\n```bash\ntsdown\n```\n\n### Library (ESM + CJS + Types)\n\n```bash\ntsdown --format esm --format cjs --dts --clean\n```\n\n### Production Build\n\n```bash\ntsdown --minify --clean --no-report\n```\n\n### Development (Watch)\n\n```bash\ntsdown --watch --sourcemap\n```\n\n### Browser Bundle (IIFE)\n\n```bash\ntsdown --format iife --platform browser --minify\n```\n\n### Node.js CLI Tool\n\n```bash\ntsdown --format esm --platform node --shims\n```\n\n### Standalone Executable\n\n```bash\ntsdown src/cli.ts --exe\n```\n\n### Monorepo Package\n\n```bash\ntsdown --clean --dts --exports --publint\n```\n\n### With Environment Variables\n\n```bash\ntsdown --env-file .env.production --env.BUILD_TIME=$(date +%s)\n```\n\n### Copy Assets\n\n```bash\ntsdown --copy public --copy assets --clean\n```\n\n## Tips\n\n1. **Use config file** for complex setups\n2. **CLI flags override** config file options\n3. **Chain multiple formats** for multi-target builds\n4. **Use --clean** to avoid stale files\n5. **Enable --dts** for TypeScript libraries\n6. **Use --watch** during development\n7. **Add --on-success** for post-build tasks\n8. **Use --exports** to auto-generate package.json fields\n\n## Related Documentation\n\n- [Config File](option-config-file.md) - Configuration file options\n- [Entry](option-entry.md) - Entry point configuration\n- [Output Format](option-output-format.md) - Format options\n- [Watch Mode](option-watch-mode.md) - Watch mode details\n","packages/rollup-plugin/README.md":"# [rollup-plugin-chrome-extension](https://www.extend-chrome.dev/rollup-plugin)\n\n[![npm (scoped)](https://img.shields.io/npm/v/rollup-plugin-chrome-extension.svg)](https://www.npmjs.com/package/rollup-plugin-chrome-extension)\n[![GitHub last commit](https://img.shields.io/github/last-commit/crxjs/rollup-plugin-chrome-extension.svg?logo=github)](https://github.com/crxjs/rollup-plugin-chrome-extension)\n![GitHub action badge](https://github.com/crxjs/rollup-plugin-chrome-extension/actions/workflows/rollup-plugin.yml/badge.svg)\n[![TypeScript Declarations Included](https://img.shields.io/badge/types-TypeScript-informational)](#typescript)\n\n\n \"rollup-plugin-chrome-extension\n\nThe bundler configuration for a Chrome Extension can be pretty complex.\n\nUse `manifest.json` as the input. Every file in the manifest will be bundled or\ncopied to the output folder.\n\nRPCE simplifies project config and supports many of Vite's features in the\nChrome Extension environment, including HMR.\n\n## [Documentation](https://www.extend-chrome.dev/rollup-plugin)\n\nWe have\n[v3 boilerplates](https://www.extend-chrome.dev/rollup-plugin#chrome-extension-boilerplates)\nfor [React JavaScript](https://github.com/crxjs/js-react-boilerplate),\n[React TypeScript](https://github.com/crxjs/ts-react-boilerplate) and\n[Svelte](https://github.com/kyrelldixon/svelte-tailwind-extension-boilerplate),\nas well as [instructions](https://www.extend-chrome.dev/rollup-plugin#usage) for\nsetting up your own project.\n\nSee the [documentation](https://www.extend-chrome.dev/rollup-plugin) for usage\nand how to get started.\n\n## Supporting\n\nIf these plugins have helped you ship your product faster, please consider\n[sponsoring me](https://github.com/sponsors/jacksteamdev) on GitHub.\n\n## Contributing\n\nWe encourage pull requests! This is a\n[pnpm monorepo](https://pnpm.io/workspaces), so use pnpm instead of Yarn or npm.\n","packages/vite-plugin/README.md":"![CRXJS](./banner-github.png)\n\n

CRXJS

\n\n

\nModern Chrome extension development with built-in HMR and zero-config setup\n

\n\n

\n\n\"NPM\n\n

\n\n

\n📚 Documentation |\n💬 Discord \n

\n\n\n## 📦 Create CRXJS Project\n```shell\nnpm create crxjs@latest\n``` \n\n> [!IMPORTANT]\n> `@latest` MUST NOT be omitted, otherwise `npm` may resolve to a cached and outdated version of the package.\n\n## ✨ Features\n\n- 🧩 **Full Vite Plugin Ecosystem** - Leverage any Vite-compatible plugins with zero extra setup \n- ⚙️ **Zero Configuration** - Start developing immediately with intelligent defaults \n- 3️⃣ **Manifest V3 Support** - Built for modern Chrome extensions with enhanced security \n- 🔥 **True Hot Module Replacement** - Instant UI updates while preserving extension state 🎈**works with content scripts**\n- 📁 **Static Asset Import** - Directly reference images/fonts in your code\n- 🤖 **Auto Web-Accessible Resources** - Automatic generation of `web_accessible_resources` manifest entries \n\n> [!NOTE] \n> Looking for MV2 support? See [`rollup-plugin`](packages/rollup-plugin/README.md) \n\n## 💻 Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for local development workflows.\n\n## 💝 Contributors\n\nThis project exists thanks to all the people who contribute.\n\nAnd thank you to all our backers! 🙏\n\n\n \n\n\n## 🤝 Supporting\n\nIf these plugins have helped you ship your product faster, please consider\n[sponsoring me](https://github.com/sponsors/jacksteamdev) on GitHub.\n"},"files":{".agents/skills/tsdown/README.md":"# tsdown Skills\n\nAgent skills that help AI coding agents understand and work with [tsdown](https://tsdown.dev), the elegant library bundler.\n\n## Installation\n\n```bash\nnpx skills add rolldown/tsdown\n```\n\nThis will install all tsdown skills (including the migration skill). To install only the tsdown skill:\n\n```bash\nnpx skills add rolldown/tsdown --skill tsdown\n```\n\n## What's Included\n\nThe tsdown skill provides Claude Code with knowledge about:\n\n- **Core Concepts** - What tsdown is, why use it, key features\n- **Configuration** - Config file formats, options, multiple configs, workspace support\n- **Build Options** - Entry points, output formats, type declarations, targets\n- **Dependency Handling** - External/inline dependencies, auto-externalization\n- **Output Enhancement** - Shims, CJS defaults, package exports\n- **Framework Support** - React, Vue, Solid, Svelte integration\n- **Advanced Features** - Plugins, hooks, programmatic API, Rolldown options\n- **CLI Commands** - All CLI options and usage patterns\n- **Migration** - Migrating from tsup to tsdown\n\n## Usage\n\nOnce installed, Claude Code will automatically use tsdown knowledge when:\n\n- Building TypeScript/JavaScript libraries\n- Configuring bundlers for library projects\n- Setting up type declaration generation\n- Working with multi-format builds (ESM, CJS, IIFE, UMD)\n- Migrating from tsup\n- Building framework component libraries\n\n### Example Prompts\n\n```\nSet up tsdown to build my TypeScript library with ESM and CJS formats\n```\n\n```\nConfigure tsdown to generate type declarations and bundle for browsers\n```\n\n```\nAdd React support to my tsdown config with Fast Refresh\n```\n\n```\nHelp me migrate from tsup to tsdown\n```\n\n```\nSet up a monorepo build with tsdown workspace support\n```\n\n## Related Skills\n\n- **[tsdown-migrate](https://github.com/rolldown/tsdown/tree/main/skills/tsdown-migrate)** - Dedicated skill for migrating from tsup to tsdown, with complete option mappings, config transformations, and troubleshooting guidance.\n\n## Documentation\n\n- [tsdown Documentation](https://tsdown.dev)\n- [GitHub Repository](https://github.com/rolldown/tsdown)\n- [Rolldown](https://rolldown.rs)\n- [Migration Guide](https://tsdown.dev/guide/migrate-from-tsup)\n\n## License\n\nMIT\n",".agents/skills/tsdown/SKILL.md":"---\nname: tsdown\ndescription: 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.\n---\n\n# tsdown - The Elegant Library Bundler\n\nBlazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.\n\n## Runtime Requirement\n\n`tsdown` requires **Node.js 22.18.0 or higher to run** (build-time only). However, the bundled output can target much lower Node.js versions via the [`target`](references/option-target.md) option, so libraries built with tsdown are **not locked to Node.js 22+ at runtime**.\n\nIf your package needs to support Node.js 18 / 20:\n\n- **Build with Node.js 22+ in CI** (e.g. set `target: 'node18'` or `target: 'node20'`).\n- **Test the built output (or the packed tarball) on the lower Node.js versions** you intend to support — e.g. using a matrix job that runs the published package's tests on Node.js 18 / 20 / 22.\n\n## When to Use\n\n- Building TypeScript/JavaScript libraries for npm\n- Generating TypeScript declaration files (.d.ts)\n- Bundling for multiple formats (ESM, CJS, IIFE, UMD)\n- Optimizing bundles with tree shaking and minification\n- Migrating from tsup with minimal changes\n- Building React, Vue, Solid, or Svelte component libraries\n\n## Quick Start\n\n```bash\n# Install\npnpm add -D tsdown\n\n# Basic usage\nnpx tsdown\n\n# With config file\nnpx tsdown --config tsdown.config.ts\n\n# Watch mode\nnpx tsdown --watch\n\n# Migrate from tsup\nnpx tsdown-migrate\n```\n\n## Basic Configuration\n\n```ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n## Core References\n\n| Topic | Description | Reference |\n|-------|-------------|-----------|\n| Getting Started | Installation, first bundle, CLI basics | [guide-getting-started](references/guide-getting-started.md) |\n| Configuration File | Config file formats, multiple configs, workspace | [option-config-file](references/option-config-file.md) |\n| CLI Reference | All CLI commands and options | [reference-cli](references/reference-cli.md) |\n| Migrate from tsup | Migration guide and compatibility notes | [guide-migrate-from-tsup](references/guide-migrate-from-tsup.md) |\n| Plugins | Rolldown, Rollup, Unplugin support | [advanced-plugins](references/advanced-plugins.md) |\n| Hooks | Lifecycle hooks for custom logic | [advanced-hooks](references/advanced-hooks.md) |\n| Programmatic API | Build from Node.js scripts, in-memory builds (`write: false`) | [advanced-programmatic](references/advanced-programmatic.md) |\n| Rolldown Options | Pass options directly to Rolldown | [advanced-rolldown-options](references/advanced-rolldown-options.md) |\n| CI Environment | CI detection, `'ci-only'` / `'local-only'` values | [advanced-ci](references/advanced-ci.md) |\n\n> For comprehensive migration assistance with complete option mappings, install the dedicated [`tsdown-migrate`](../tsdown-migrate/SKILL.md) skill: `npx skills add rolldown/tsdown --skill tsdown-migrate`\n\n## Build Options\n\n| Option | Usage | Reference |\n|--------|-------|-----------|\n| Entry points | `entry: ['src/*.ts', '!**/*.test.ts']` | [option-entry](references/option-entry.md) |\n| Output formats | `format: ['esm', 'cjs', 'iife', 'umd']` | [option-output-format](references/option-output-format.md) |\n| Output directory | `outDir: 'dist'`, `outExtensions` | [option-output-directory](references/option-output-directory.md) |\n| Type declarations | `dts: true`, `dts: { sourcemap, compilerOptions, vue }` | [option-dts](references/option-dts.md) |\n| Target environment | `target: 'es2020'`, `target: 'esnext'` | [option-target](references/option-target.md) |\n| Platform | `platform: 'node'`, `platform: 'browser'` | [option-platform](references/option-platform.md) |\n| Tree shaking | `treeshake: true`, custom options | [option-tree-shaking](references/option-tree-shaking.md) |\n| Minification | `minify: true`, `minify: 'dce-only'` | [option-minification](references/option-minification.md) |\n| Source maps | `sourcemap: true`, `'inline'`, `'hidden'` | [option-sourcemap](references/option-sourcemap.md) |\n| Watch mode | `watch: true`, watch options | [option-watch-mode](references/option-watch-mode.md) |\n| Cleaning | `clean: true`, clean patterns | [option-cleaning](references/option-cleaning.md) |\n| Log level | `logLevel: 'silent'`, `failOnWarn: false`, `suppressWarnings: [...]` | [option-log-level](references/option-log-level.md) |\n\n## Dependency Handling\n\n| Feature | Usage | Reference |\n|---------|-------|-----------|\n| Never bundle | `deps: { neverBundle: ['react', /^@myorg\\//] }` | [option-dependencies](references/option-dependencies.md) |\n| Always bundle | `deps: { alwaysBundle: ['dep-to-bundle'] }` | [option-dependencies](references/option-dependencies.md) |\n| Only bundle | `deps: { onlyBundle: ['cac', 'bumpp'] }` - Whitelist | [option-dependencies](references/option-dependencies.md) |\n| Only import | `deps: { onlyImport: ['cac'] }` - Whitelist runtime imports in output | [option-dependencies](references/option-dependencies.md) |\n| Externalize all | `deps: { neverBundle: true }` | [option-dependencies](references/option-dependencies.md) |\n| Resolve subpaths | `deps: { resolveDepSubpath: true }` - Resolve external subpath imports (default `false`) | [option-dependencies](references/option-dependencies.md) |\n| Auto external | Automatic dependency/peer/optional externalization | [option-dependencies](references/option-dependencies.md) |\n\n## Output Enhancement\n\n| Feature | Usage | Reference |\n|---------|-------|-----------|\n| Shims | `shims: true` - Add ESM/CJS compatibility | [option-shims](references/option-shims.md) |\n| CJS default | `cjsDefault: true` (default) / `false` | [option-cjs-default](references/option-cjs-default.md) |\n| Package exports | `exports: true` - Generate exports field | [option-package-exports](references/option-package-exports.md) |\n| CSS handling | **[experimental]** `css: { ... }` — full pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, code splitting; requires `@tsdown/css` | [option-css](references/option-css.md) |\n| CSS modules | `css: { modules: { localsConvention: 'camelCase' } }` — scoped class names for `.module.css` files | [option-css](references/option-css.md) |\n| CSS inject | `css: { inject: true }` — preserve CSS imports in JS output | [option-css](references/option-css.md) |\n| Copy files | `copy: 'public'` or `copy: { from, to, flatten, rename }` - Copy static assets to output | [option-copy](references/option-copy.md) |\n| Unbundle mode | `unbundle: true` - Preserve directory structure | [option-unbundle](references/option-unbundle.md) |\n| Root directory | `root: 'src'` - Control output directory mapping | [option-root](references/option-root.md) |\n| Executable | **[experimental]** `exe: true` - Bundle as standalone executable, cross-platform via `@tsdown/exe` | [option-exe](references/option-exe.md) |\n| Package validation | `publint: true`, `attw: true` - Validate package | [option-lint](references/option-lint.md) |\n\n## Framework & Runtime Support\n\n| Framework | Guide | Reference |\n|-----------|-------|-----------|\n| React | JSX transform, React Compiler | [recipe-react](references/recipe-react.md) |\n| Vue | SFC support, JSX | [recipe-vue](references/recipe-vue.md) |\n| Solid | SolidJS JSX transform | [recipe-solid](references/recipe-solid.md) |\n| Svelte | Svelte component libraries (source distribution recommended) | [recipe-svelte](references/recipe-svelte.md) |\n| WASM | WebAssembly modules via `rolldown-plugin-wasm` | [recipe-wasm](references/recipe-wasm.md) |\n\n## Common Patterns\n\n### Basic Library Bundle\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### Browser Library (IIFE/UMD)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n globalName: 'MyLib',\n platform: 'browser',\n minify: true,\n})\n```\n\n### React Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.tsx'],\n format: ['esm', 'cjs'],\n dts: true,\n deps: {\n neverBundle: ['react', 'react-dom'],\n },\n inputOptions: {\n jsx: { runtime: 'automatic' },\n },\n})\n```\n\n### Preserve Directory Structure\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n unbundle: true, // Preserve file structure\n format: ['esm'],\n dts: true,\n})\n```\n\n### CI-Aware Configuration\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n failOnWarn: 'ci-only', // opt-in: fail on warnings in CI\n publint: 'ci-only',\n attw: 'ci-only',\n})\n```\n\n### WASM Support\n\n```ts\nimport { wasm } from 'rolldown-plugin-wasm'\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [wasm()],\n})\n```\n\n### Library with CSS and Sass\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n target: 'chrome100',\n css: {\n preprocessorOptions: {\n scss: {\n additionalData: `@use \"src/styles/variables\" as *;`,\n },\n },\n },\n})\n```\n\n### Standalone Executable\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: true,\n})\n```\n\n### Cross-Platform Executable (requires `@tsdown/exe`)\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [\n { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },\n { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },\n { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },\n ],\n },\n})\n```\n\n### Advanced with Hooks\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n hooks: {\n 'build:before': async (context) => {\n console.log('Building...')\n },\n 'build:done': async (context) => {\n console.log('Build complete!')\n },\n },\n})\n```\n\n## Configuration Features\n\n### Multiple Configs\n\nExport an array for multiple build configurations:\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n },\n {\n entry: ['src/cli.ts'],\n format: ['esm'],\n platform: 'node',\n },\n])\n```\n\n### Conditional Config\n\nUse functions for dynamic configuration:\n\n```ts\nexport default defineConfig((options) => {\n const isDev = options.watch\n return {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n }\n})\n```\n\n### Workspace/Monorepo\n\nUse glob patterns to build multiple packages:\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n## CLI Quick Reference\n\n```bash\n# Basic commands\ntsdown # Build once\ntsdown --watch # Watch mode\ntsdown --config custom.ts # Custom config\nnpx tsdown-migrate # Migrate from tsup\n\n# Output options\ntsdown --format esm,cjs # Multiple formats\ntsdown -d lib # Custom output directory (--out-dir)\ntsdown --minify # Enable minification\ntsdown --dts # Generate declarations\ntsdown --exe # Bundle as standalone executable\ntsdown --unbundle # Bundleless mode\ntsdown --copy public # Copy static files to output\n\n# Entry options\ntsdown src/index.ts # Single entry\ntsdown src/*.ts # Glob patterns\ntsdown src/a.ts src/b.ts # Multiple entries\n\n# Workspace / Monorepo\ntsdown -W # Enable workspace mode\ntsdown -W -F my-package # Filter specific package\ntsdown --filter /^pkg-/ # Filter by regex\ntsdown -W --concurrency 4 # Limit parallel Rolldown builds\n\n# Development\ntsdown --watch # Watch mode\ntsdown --sourcemap # Generate source maps\ntsdown --clean # Clean output directory\ntsdown --from-vite # Reuse Vite config\ntsdown --tsconfig tsconfig.build.json # Custom tsconfig\n```\n\n## Best Practices\n\n1. **Always generate type declarations** for TypeScript libraries:\n ```ts\n { dts: true }\n ```\n\n2. **Externalize dependencies** to avoid bundling unnecessary code:\n ```ts\n { deps: { neverBundle: [/^react/, /^@myorg\\//] } }\n ```\n\n3. **Use tree shaking** for optimal bundle size:\n ```ts\n { treeshake: true }\n ```\n\n4. **Enable minification** for production builds:\n ```ts\n { minify: true }\n ```\n\n5. **Add shims** for better ESM/CJS compatibility:\n ```ts\n { shims: true } // Adds __dirname, __filename, etc.\n ```\n\n6. **Auto-generate package.json exports**:\n ```ts\n { exports: true } // Creates proper exports field\n ```\n\n7. **Use watch mode** during development:\n ```bash\n tsdown --watch\n ```\n\n8. **Preserve structure** for utilities with many files:\n ```ts\n { unbundle: true } // Keep directory structure\n ```\n\n9. **Validate packages** in CI before publishing:\n ```ts\n { publint: 'ci-only', attw: 'ci-only' }\n ```\n\n## Resources\n\n- Documentation: https://tsdown.dev\n- GitHub: https://github.com/rolldown/tsdown\n- Rolldown: https://rolldown.rs\n- Migration Guide: https://tsdown.dev/guide/migrate-from-tsup\n",".agents/skills/tsdown/references/README.md":"# tsdown Skill References\n\nThis directory contains detailed reference documentation for the tsdown skill.\n\n## Created Files (38 total)\n\n### Core Guides (3)\n- ✅ `guide-getting-started.md` - Installation, first bundle, CLI basics\n- ✅ `guide-migrate-from-tsup.md` - Migration guide from tsup\n- ✅ `guide-introduction.md` - Introduction and key features\n\n### Configuration Options (22)\n- ✅ `option-config-file.md` - Config file formats, loaders, workspace\n- ✅ `option-entry.md` - Entry point configuration with globs\n- ✅ `option-output-format.md` - Output formats (ESM, CJS, IIFE, UMD)\n- ✅ `option-output-directory.md` - Output directory and extensions\n- ✅ `option-dts.md` - TypeScript declaration generation\n- ✅ `option-target.md` - Target environment (ES2020, ESNext, etc.)\n- ✅ `option-platform.md` - Platform (node, browser, neutral)\n- ✅ `option-dependencies.md` - External and inline dependencies\n- ✅ `option-sourcemap.md` - Source map generation\n- ✅ `option-minification.md` - Minification (`boolean | 'dce-only' | MinifyOptions`)\n- ✅ `option-tree-shaking.md` - Tree shaking configuration\n- ✅ `option-cleaning.md` - Output directory cleaning\n- ✅ `option-watch-mode.md` - Watch mode configuration\n- ✅ `option-shims.md` - ESM/CJS compatibility shims\n- ✅ `option-package-exports.md` - Auto-generate package.json exports\n- ✅ `option-css.md` - CSS handling (experimental, full pipeline: preprocessors, Lightning CSS, PostCSS, code splitting)\n- ✅ `option-unbundle.md` - Preserve directory structure\n- ✅ `option-root.md` - Root directory for output structure mapping\n- ✅ `option-copy.md` - Copy static files to output\n- ✅ `option-cjs-default.md` - CommonJS default export handling\n- ✅ `option-log-level.md` - Logging configuration\n- ✅ `option-lint.md` - Package validation (publint & attw)\n\n### Executable (1)\n- ✅ `option-exe.md` - Standalone executable bundling (Node.js SEA)\n\n### Advanced Topics (6)\n- ✅ `advanced-plugins.md` - Rolldown, Rollup, Unplugin support\n- ✅ `advanced-hooks.md` - Lifecycle hooks system\n- ✅ `advanced-programmatic.md` - Node.js API usage\n- ✅ `advanced-rolldown-options.md` - Pass options to Rolldown\n- ✅ `advanced-ci.md` - CI environment detection and CI-aware options\n\n### Advanced (continued)\n- ✅ `advanced-benchmark.md` - Performance benchmarks\n\n### Framework Recipes (5)\n- ✅ `recipe-react.md` - React library setup with JSX\n- ✅ `recipe-vue.md` - Vue library setup with SFC\n- ✅ `recipe-solid.md` - Solid.js library setup\n- ✅ `recipe-svelte.md` - Svelte component libraries\n- ✅ `recipe-wasm.md` - WASM module support\n\n### Reference (1)\n- ✅ `reference-cli.md` - Complete CLI command reference\n\n## Coverage Status\n\n**Created:** 38 files (100% complete)\n\n## Current Skill Features\n\nThe tsdown skill now includes comprehensive coverage of:\n\n### ✅ Core Functionality\n- Getting started and installation\n- Entry points and glob patterns\n- Output formats (ESM, CJS, IIFE, UMD)\n- TypeScript declarations\n- Configuration file setup\n- CLI reference\n\n### ✅ Build Options\n- Target environment configuration\n- Platform selection\n- Dependency management\n- Source maps\n- Minification\n- Tree shaking\n- Output cleaning\n- Watch mode\n\n### ✅ Advanced Features\n- Plugins (Rolldown, Rollup, Unplugin)\n- Lifecycle hooks\n- ESM/CJS shims\n- Package exports generation\n- Package validation (publint, attw)\n- Programmatic API (Node.js)\n- Output directory customization\n- CSS handling and modules\n- Unbundle mode\n- CI environment detection and CI-aware options\n\n### ✅ Framework & Runtime Support\n- React with JSX/TSX\n- React Compiler integration\n- Vue with SFC support\n- Vue type generation (vue-tsc)\n- WASM module bundling (rolldown-plugin-wasm)\n\n### ✅ Migration\n- Complete migration guide from tsup\n- Compatibility notes\n\n## Usage\n\nThe skill is now ready for use with comprehensive coverage of core features. Additional files can be added incrementally as needed.\n\n## File Naming Convention\n\nFiles are prefixed by category:\n- `guide-*` - Getting started guides and tutorials\n- `option-*` - Configuration options\n- `advanced-*` - Advanced topics (plugins, hooks, programmatic API)\n- `recipe-*` - Framework-specific recipes\n- `reference-*` - CLI and API reference\n\n## Creating New Reference Files\n\nWhen creating new reference files:\n\n1. **Read source documentation** from `/docs` directory\n2. **Simplify for AI consumption** - concise, actionable content\n3. **Include code examples** - practical, copy-paste ready\n4. **Add cross-references** - link to related options\n5. **Follow naming convention** - use appropriate prefix\n6. **Keep it focused** - one topic per file\n\n## Updating Existing Files\n\nWhen documentation changes:\n\n1. Check git diff: `git diff ..HEAD -- docs/`\n2. Update affected reference files\n3. Update SKILL.md if needed\n4. Update GENERATION.md with new SHA\n\nSee `skills/GENERATION.md` for detailed update instructions.\n",".agents/skills/tsdown/references/advanced-benchmark.md":"# Benchmark\n\ntsdown delivers exceptional performance:\n\n- **~2x faster** than tsup for standard builds\n- **Up to 8x faster** for TypeScript declaration generation\n\nFor detailed comparisons, see [bundler-benchmark](https://gugustinette.github.io/bundler-benchmark/).\n",".agents/skills/tsdown/references/advanced-ci.md":"# CI Environment Support\n\nAutomatically detect CI environments and toggle features based on local vs CI builds.\n\n## Overview\n\ntsdown detects CI from the `CI` environment variable. CI mode is enabled when `process.env.CI` is set to a value other than `0` or `false` (case-insensitive).\n\n## CI-Aware Values\n\nSeveral options accept CI-aware string values:\n\n| Value | Behavior |\n|-------|----------|\n| `true` | Always enabled |\n| `false` | Always disabled |\n| `'ci-only'` | Enabled only in CI, disabled locally |\n| `'local-only'` | Enabled only locally, disabled in CI |\n\n## Supported Options\n\nThese options accept CI-aware values:\n\n- `dts` - TypeScript declaration file generation\n- `publint` - Package lint validation\n- `attw` - \"Are the types wrong\" validation\n- `report` - Bundle size reporting\n- `exports` - Auto-generate `package.json` exports\n- `unused` - Unused dependency check\n- `devtools` - DevTools integration\n- `failOnWarn` - Fail on warnings (defaults to `false`)\n\n## Usage\n\n### String Form\n\n```ts\nexport default defineConfig({\n dts: 'local-only', // Skip DTS in CI for faster builds\n publint: 'ci-only', // Only run publint in CI\n failOnWarn: 'ci-only', // Fail on warnings in CI only (opt-in)\n})\n```\n\n### Object Form\n\nWhen an option takes a configuration object, set `enabled` to a CI-aware value:\n\n```ts\nexport default defineConfig({\n publint: {\n enabled: 'ci-only',\n level: 'error',\n },\n attw: {\n enabled: 'ci-only',\n profile: 'node16',\n },\n})\n```\n\n### Config Function\n\nThe config function receives a `ci` boolean in its context:\n\n```ts\nexport default defineConfig((_, { ci }) => ({\n minify: ci,\n sourcemap: !ci,\n}))\n```\n\n## Typical CI Configuration\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n dts: true,\n failOnWarn: 'ci-only',\n publint: 'ci-only',\n attw: 'ci-only',\n})\n```\n\n## Related Options\n\n- [Package Validation](option-lint.md) - publint and attw configuration\n- [Log Level](option-log-level.md) - `failOnWarn` option details\n",".agents/skills/tsdown/references/advanced-hooks.md":"# Lifecycle Hooks\n\nExtend the build process with lifecycle hooks.\n\n## Overview\n\nHooks provide a way to inject custom logic at specific stages of the build lifecycle. Inspired by [unbuild](https://github.com/unjs/unbuild).\n\n**Recommendation:** Use [plugins](advanced-plugins.md) for most extensions. Use hooks for simple custom tasks or Rolldown plugin injection.\n\n## Usage Patterns\n\n### Object Syntax\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n hooks: {\n 'build:prepare': async (context) => {\n console.log('Build starting...')\n },\n 'build:done': async (context) => {\n console.log('Build complete!')\n },\n },\n})\n```\n\n### Function Syntax\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n hooks(hooks) {\n hooks.hook('build:prepare', () => {\n console.log('Preparing build...')\n })\n\n hooks.hook('build:before', (context) => {\n console.log(`Building format: ${context.format}`)\n })\n },\n})\n```\n\n## Available Hooks\n\n### `build:prepare`\n\nCalled before the build process starts.\n\n**When:** Once per build session\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Setup tasks\n- Validation\n- Environment preparation\n\n**Example:**\n```ts\nhooks: {\n 'build:prepare': async (context) => {\n console.log('Starting build for:', context.options.entry)\n await cleanOldFiles()\n },\n}\n```\n\n### `build:before`\n\nCalled before each Rolldown build.\n\n**When:** Once per format (ESM, CJS, etc.)\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n buildOptions: BuildOptions,\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Modify build options per format\n- Inject plugins dynamically\n- Format-specific setup\n\n**Example:**\n```ts\nhooks: {\n 'build:before': async (context) => {\n console.log(`Building ${context.buildOptions.format} format...`)\n\n // Add format-specific plugin\n if (context.buildOptions.format === 'iife') {\n context.buildOptions.plugins.push(browserPlugin())\n }\n },\n}\n```\n\n### `build:done`\n\nCalled after the build completes.\n\n**When:** Once per build session\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n chunks: RolldownChunk[],\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Post-processing\n- Asset copying\n- Notifications\n- Deployment\n\n**Example:**\n```ts\nhooks: {\n 'build:done': async (context) => {\n console.log(`Built ${context.chunks.length} chunks`)\n\n // Copy additional files\n await copyAssets()\n\n // Send notification\n notifyBuildComplete()\n },\n}\n```\n\n## Common Patterns\n\n### Build Notifications\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': () => {\n console.log('🚀 Starting build...')\n },\n 'build:done': (context) => {\n const size = context.chunks.reduce((sum, c) => sum + c.code.length, 0)\n console.log(`✅ Build complete! Total size: ${size} bytes`)\n },\n },\n})\n```\n\n### Conditional Plugin Injection\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n hooks.hook('build:before', (context) => {\n // Add minification only for production\n if (process.env.NODE_ENV === 'production') {\n context.buildOptions.plugins.push(minifyPlugin())\n }\n })\n },\n})\n```\n\n### Custom File Copy\n\n```ts\nimport { copyFile } from 'fs/promises'\n\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n // Copy README to dist\n await copyFile('README.md', `${context.options.outDir}/README.md`)\n },\n },\n})\n```\n\n### Build Metrics\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': (context) => {\n context.startTime = Date.now()\n },\n 'build:done': (context) => {\n const duration = Date.now() - context.startTime\n console.log(`Build took ${duration}ms`)\n\n // Log chunk sizes\n context.chunks.forEach((chunk) => {\n console.log(`${chunk.fileName}: ${chunk.code.length} bytes`)\n })\n },\n },\n})\n```\n\n### Format-Specific Logic\n\n```ts\nexport default defineConfig({\n format: ['esm', 'cjs', 'iife'],\n hooks: {\n 'build:before': (context) => {\n const format = context.buildOptions.format\n\n if (format === 'iife') {\n // Browser-specific setup\n context.buildOptions.globalName = 'MyLib'\n } else if (format === 'cjs') {\n // Node-specific setup\n context.buildOptions.platform = 'node'\n }\n },\n },\n})\n```\n\n### Deployment Hook\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n if (process.env.DEPLOY === 'true') {\n console.log('Deploying to CDN...')\n await deployToCDN(context.options.outDir)\n }\n },\n },\n})\n```\n\n## Advanced Usage\n\n### Multiple Hooks\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n // Register multiple hooks\n hooks.hook('build:prepare', setupEnvironment)\n hooks.hook('build:prepare', validateConfig)\n\n hooks.hook('build:before', injectPlugins)\n hooks.hook('build:before', logFormat)\n\n hooks.hook('build:done', generateManifest)\n hooks.hook('build:done', notifyComplete)\n },\n})\n```\n\n### Async Hooks\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': async (context) => {\n await fetchRemoteConfig()\n await initializeDatabase()\n },\n 'build:done': async (context) => {\n await uploadToS3(context.chunks)\n await invalidateCDN()\n },\n },\n})\n```\n\n### Error Handling\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n try {\n await riskyOperation()\n } catch (error) {\n console.error('Hook failed:', error)\n // Don't throw - allow build to complete\n }\n },\n },\n})\n```\n\n## Hookable API\n\ntsdown uses [hookable](https://github.com/unjs/hookable) for hooks. Additional methods:\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n // Register hook\n hooks.hook('build:done', handler)\n\n // Register hook once\n hooks.hookOnce('build:prepare', handler)\n\n // Remove hook\n hooks.removeHook('build:done', handler)\n\n // Clear all hooks for event\n hooks.removeHooks('build:done')\n\n // Call hooks manually\n await hooks.callHook('build:done', context)\n },\n})\n```\n\n## Tips\n\n1. **Use plugins** for most extensions\n2. **Hooks for simple tasks** like notifications or file copying\n3. **Async hooks supported** for I/O operations\n4. **Don't throw errors** unless you want to fail the build\n5. **Context is mutable** in `build:before` for advanced use cases\n6. **Multiple hooks allowed** for the same event\n\n## Troubleshooting\n\n### Hook Not Called\n\n- Verify hook name is correct\n- Check hook is registered in config\n- Ensure async hooks are awaited\n\n### Build Fails in Hook\n\n- Add try/catch for error handling\n- Don't throw unless intentional\n- Log errors for debugging\n\n### Context Undefined\n\n- Check which hook you're using\n- Verify context properties available for that hook\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Rolldown Options](advanced-rolldown-options.md) - Build options\n- [Watch Mode](option-watch-mode.md) - Development workflow\n",".agents/skills/tsdown/references/advanced-plugins.md":"# Plugins\n\nExtend tsdown with plugins from multiple ecosystems.\n\n## Overview\n\ntsdown, built on Rolldown, supports plugins from multiple ecosystems to extend and customize the bundling process.\n\n## Supported Ecosystems\n\n### 1. Rolldown Plugins\n\nNative plugins designed for Rolldown:\n\n```ts\nimport RolldownPlugin from 'rolldown-plugin-something'\n\nexport default defineConfig({\n plugins: [RolldownPlugin()],\n})\n```\n\n**Compatibility:** ✅ Full support\n\n### 2. Unplugin\n\nUniversal plugins that work across bundlers:\n\n```ts\nimport UnpluginPlugin from 'unplugin-something'\n\nexport default defineConfig({\n plugins: [UnpluginPlugin.rolldown()],\n})\n```\n\n**Compatibility:** ✅ Most unplugin-* plugins work\n\n**Examples:**\n- `unplugin-vue-components`\n- `unplugin-auto-import`\n- `unplugin-icons`\n\n### 3. Rollup Plugins\n\nMost Rollup plugins work with tsdown:\n\n```ts\nimport RollupPlugin from '@rollup/plugin-something'\n\nexport default defineConfig({\n plugins: [RollupPlugin()],\n})\n```\n\n**Compatibility:** ✅ High compatibility\n\n**Type Issues:** May cause TypeScript errors - use type casting:\n\n```ts\nimport RollupPlugin from 'rollup-plugin-something'\n\nexport default defineConfig({\n plugins: [\n // @ts-expect-error Rollup plugin type mismatch\n RollupPlugin(),\n // Or cast to any\n RollupPlugin() as any,\n ],\n})\n```\n\n### 4. Vite Plugins\n\nSome Vite plugins may work:\n\n```ts\nimport VitePlugin from 'vite-plugin-something'\n\nexport default defineConfig({\n plugins: [\n // @ts-expect-error Vite plugin type mismatch\n VitePlugin(),\n ],\n})\n```\n\n**Compatibility:** ⚠️ Limited - only if not using Vite-specific APIs\n\n**Note:** Improved support planned for future releases.\n\n## Usage\n\n### Basic Plugin Usage\n\n```ts\nimport { defineConfig } from 'tsdown'\nimport SomePlugin from 'some-plugin'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [SomePlugin()],\n})\n```\n\n### Multiple Plugins\n\n```ts\nimport PluginA from 'plugin-a'\nimport PluginB from 'plugin-b'\nimport PluginC from 'plugin-c'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n PluginA(),\n PluginB({ option: true }),\n PluginC(),\n ],\n})\n```\n\n### Conditional Plugins\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n plugins: [\n SomePlugin(),\n options.watch && DevPlugin(),\n !options.watch && ProdPlugin(),\n ].filter(Boolean),\n}))\n```\n\n## Common Plugin Patterns\n\n### JSON Import\n\n```ts\nimport json from '@rollup/plugin-json'\n\nexport default defineConfig({\n plugins: [json()],\n})\n```\n\n### Node Resolve\n\n```ts\nimport { nodeResolve } from '@rollup/plugin-node-resolve'\n\nexport default defineConfig({\n plugins: [nodeResolve()],\n})\n```\n\n### CommonJS\n\n```ts\nimport commonjs from '@rollup/plugin-commonjs'\n\nexport default defineConfig({\n plugins: [commonjs()],\n})\n```\n\n### Replace\n\n```ts\nimport replace from '@rollup/plugin-replace'\n\nexport default defineConfig({\n plugins: [\n replace({\n 'process.env.NODE_ENV': JSON.stringify('production'),\n __VERSION__: JSON.stringify('1.0.0'),\n }),\n ],\n})\n```\n\n### Auto Import\n\n```ts\nimport AutoImport from 'unplugin-auto-import/rolldown'\n\nexport default defineConfig({\n plugins: [\n AutoImport({\n imports: ['vue', 'vue-router'],\n dts: 'src/auto-imports.d.ts',\n }),\n ],\n})\n```\n\n### Vue Components\n\n```ts\nimport Components from 'unplugin-vue-components/rolldown'\n\nexport default defineConfig({\n plugins: [\n Components({\n dts: 'src/components.d.ts',\n }),\n ],\n})\n```\n\n## Framework-Specific Plugins\n\n### React\n\n```ts\nimport react from '@vitejs/plugin-react'\n\nexport default defineConfig({\n entry: ['src/index.tsx'],\n plugins: [\n // @ts-expect-error Vite plugin\n react(),\n ],\n})\n```\n\n### Vue\n\n```ts\nimport vue from '@vitejs/plugin-vue'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n // @ts-expect-error Vite plugin\n vue(),\n ],\n})\n```\n\n### Solid\n\n```ts\nimport solid from 'vite-plugin-solid'\n\nexport default defineConfig({\n entry: ['src/index.tsx'],\n plugins: [\n // @ts-expect-error Vite plugin\n solid(),\n ],\n})\n```\n\n### Svelte\n\n```ts\nimport { svelte } from '@sveltejs/vite-plugin-svelte'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n // @ts-expect-error Vite plugin\n svelte(),\n ],\n})\n```\n\n## Writing Custom Plugins\n\nFollow Rolldown's plugin development guide:\n\n### Basic Plugin Structure\n\n```ts\nimport type { Plugin } from 'rolldown'\n\nfunction myPlugin(): Plugin {\n return {\n name: 'my-plugin',\n\n // Transform hook\n transform(code, id) {\n if (id.endsWith('.custom')) {\n return {\n code: transformCode(code),\n map: null,\n }\n }\n },\n\n // Other hooks...\n }\n}\n```\n\n### Using Custom Plugin\n\n```ts\nimport { myPlugin } from './my-plugin'\n\nexport default defineConfig({\n plugins: [myPlugin()],\n})\n```\n\n## Plugin Configuration\n\n### Plugin-Specific Options\n\nRefer to each plugin's documentation for configuration options.\n\n### Plugin Order\n\nPlugins run in the order they're defined:\n\n```ts\nexport default defineConfig({\n plugins: [\n PluginA(), // Runs first\n PluginB(), // Runs second\n PluginC(), // Runs last\n ],\n})\n```\n\n## Troubleshooting\n\n### Type Errors with Rollup/Vite Plugins\n\nUse type casting:\n\n```ts\nplugins: [\n // Option 1: @ts-expect-error\n // @ts-expect-error Plugin type mismatch\n SomePlugin(),\n\n // Option 2: as any\n SomePlugin() as any,\n]\n```\n\n### Plugin Not Working\n\n1. **Check compatibility** - Verify plugin supports your bundler\n2. **Read documentation** - Follow plugin's setup instructions\n3. **Check plugin order** - Some plugins depend on execution order\n4. **Enable debug mode** - Use `--debug` flag\n\n### Vite Plugin Fails\n\nVite plugins may rely on Vite-specific APIs:\n\n1. **Find Rollup equivalent** - Look for Rollup version of plugin\n2. **Use Unplugin version** - Check for `unplugin-*` alternative\n3. **Wait for support** - Vite plugin support improving\n\n## Resources\n\n- [Rolldown Plugin Development](https://rolldown.rs/apis/plugin-api)\n- [Unplugin Documentation](https://unplugin.unjs.io/)\n- [Rollup Plugins](https://github.com/rollup/plugins)\n- [Vite Plugins](https://vitejs.dev/plugins/)\n\n## Tips\n\n1. **Prefer Rolldown plugins** for best compatibility\n2. **Use Unplugin** for cross-bundler support\n3. **Cast types** for Rollup/Vite plugins\n4. **Test thoroughly** when using cross-ecosystem plugins\n5. **Check plugin docs** for specific configuration\n6. **Write custom plugins** for unique needs\n\n## Related\n\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [Rolldown Options](advanced-rolldown-options.md) - Advanced Rolldown config\n- [React Recipe](recipe-react.md) - React setup with plugins\n- [Vue Recipe](recipe-vue.md) - Vue setup with plugins\n",".agents/skills/tsdown/references/advanced-programmatic.md":"# Programmatic Usage\n\nUse tsdown from JavaScript/TypeScript code.\n\n## Overview\n\ntsdown can be imported and used programmatically in your Node.js scripts, custom build tools, or automation workflows.\n\n## Basic Usage\n\n### Simple Build\n\n```ts\nimport { build } from 'tsdown'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### With Options\n\n```ts\nimport { build } from 'tsdown'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n dts: true,\n minify: true,\n sourcemap: true,\n clean: true,\n})\n```\n\n### In-Memory Output\n\nSet `write: false` to access generated chunks and assets without writing the\nbundle output to disk:\n\n```ts\nimport { build } from 'tsdown'\n\nconst bundles = await build({\n entry: ['src/index.ts'],\n format: 'esm',\n write: false,\n clean: false,\n})\n\nfor (const bundle of bundles) {\n for (const output of bundle.chunks) {\n const contents = output.type === 'chunk' ? output.code : output.source\n console.log(output.fileName, contents)\n }\n}\n```\n\n`build()` currently returns a `TsdownBundle[]`, with one bundle for each\nresolved configuration. Even a single configuration returns an array; its\nin-memory Rolldown outputs are available in `bundle.chunks`.\n\nThe `write` option controls Rolldown's bundle output, while other file operations\nare configured separately. For example, `clean` defaults to `true`, so set\n`clean: false` as above if existing output directories must remain untouched.\nExplicitly enabled features such as `copy` or `exports` may still write files.\n`write: false` is incompatible with watch mode.\n\n## API Reference\n\n### build()\n\nMain function to run a build.\n\n```ts\nimport { build } from 'tsdown'\n\nawait build(options)\n```\n\n**Parameters:**\n- `options` - Build configuration object (same as config file)\n\n**Returns:**\n- `Promise` - One bundle for each resolved configuration\n\n**Throws:**\n- Build errors if compilation fails\n\n## Configuration Object\n\nAll config file options are available:\n\n```ts\nimport { build, defineConfig } from 'tsdown'\n\nconst config = defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: true,\n sourcemap: true,\n deps: {\n neverBundle: ['react', 'react-dom'],\n },\n plugins: [/* plugins */],\n hooks: {\n 'build:done': async () => {\n console.log('Build complete!')\n },\n },\n})\n\nawait build(config)\n```\n\nSee [Config Reference](option-config-file.md) for all options.\n\n## Common Patterns\n\n### Custom Build Script\n\n```ts\n// scripts/build.ts\nimport { build } from 'tsdown'\n\nasync function main() {\n console.log('Building library...')\n\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n })\n\n console.log('Build complete!')\n}\n\nmain().catch(console.error)\n```\n\nRun with:\n```bash\ntsx scripts/build.ts\n```\n\n### Multiple Builds\n\n```ts\nimport { build } from 'tsdown'\n\n// Build main library\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n dts: true,\n})\n\n// Build CLI tool\nawait build({\n entry: ['src/cli.ts'],\n format: ['esm'],\n outDir: 'dist/bin',\n platform: 'node',\n shims: true,\n})\n```\n\n### Conditional Build\n\n```ts\nimport { build } from 'tsdown'\n\nconst isDev = process.env.NODE_ENV === 'development'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n clean: !isDev,\n})\n```\n\n### With Error Handling\n\n```ts\nimport { build } from 'tsdown'\n\ntry {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n })\n console.log('✅ Build successful')\n} catch (error) {\n console.error('❌ Build failed:', error)\n process.exit(1)\n}\n```\n\n### Automated Workflow\n\n```ts\nimport { build } from 'tsdown'\nimport { execSync } from 'child_process'\n\nasync function release() {\n // Clean\n console.log('Cleaning...')\n execSync('rm -rf dist')\n\n // Build\n console.log('Building...')\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: true,\n })\n\n // Test\n console.log('Testing...')\n execSync('npm test')\n\n // Publish\n console.log('Publishing...')\n execSync('npm publish')\n}\n\nrelease().catch(console.error)\n```\n\n### Build with Post-Processing\n\n```ts\nimport { build } from 'tsdown'\nimport { copyFileSync } from 'fs'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n hooks: {\n 'build:done': async () => {\n // Copy additional files\n copyFileSync('README.md', 'dist/README.md')\n copyFileSync('LICENSE', 'dist/LICENSE')\n console.log('Copied additional files')\n },\n },\n})\n```\n\n## Watch Mode\n\nUnfortunately, watch mode is not directly exposed in the programmatic API. Use the CLI for watch mode:\n\n```ts\n// Use CLI for watch mode\nimport { spawn } from 'child_process'\n\nspawn('tsdown', ['--watch'], {\n stdio: 'inherit',\n shell: true,\n})\n```\n\n## Integration Examples\n\n### With Task Runner\n\n```ts\n// gulpfile.js\nimport { build } from 'tsdown'\nimport gulp from 'gulp'\n\ngulp.task('build', async () => {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n })\n})\n\ngulp.task('watch', () => {\n return gulp.watch('src/**/*.ts', gulp.series('build'))\n})\n```\n\n### With Custom CLI\n\n```ts\n// scripts/cli.ts\nimport { build } from 'tsdown'\nimport { Command } from 'commander'\n\nconst program = new Command()\n\nprogram\n .command('build')\n .option('--prod', 'Production build')\n .action(async (options) => {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: options.prod,\n sourcemap: !options.prod,\n })\n })\n\nprogram.parse()\n```\n\n### With CI/CD\n\n```ts\n// .github/scripts/build.ts\nimport { build } from 'tsdown'\n\nconst isCI = process.env.CI === 'true'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: isCI,\n clean: true,\n})\n\n// Upload to artifact storage\nif (isCI) {\n // Upload dist/ to S3, etc.\n}\n```\n\n## TypeScript Support\n\n```ts\n// scripts/build.ts\nimport { build, type UserConfig } from 'tsdown'\n\nconst config: UserConfig = {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n}\n\nawait build(config)\n```\n\n## Tips\n\n1. **Use TypeScript** for type safety\n2. **Handle errors** properly\n3. **Use hooks** for custom logic\n4. **Log progress** for visibility\n5. **Use CLI for watch** mode\n6. **Exit on error** in scripts\n\n## Troubleshooting\n\n### Import Errors\n\nEnsure tsdown is installed:\n```bash\npnpm add -D tsdown\n```\n\n### Type Errors\n\nImport types:\n```ts\nimport type { UserConfig } from 'tsdown'\n```\n\n### Build Fails Silently\n\nAdd error handling:\n```ts\ntry {\n await build(config)\n} catch (error) {\n console.error(error)\n process.exit(1)\n}\n```\n\n### Options Not Working\n\nCheck spelling and types:\n```ts\n// ✅ Correct\n{ format: ['esm', 'cjs'] }\n\n// ❌ Wrong\n{ formats: ['esm', 'cjs'] }\n```\n\n## Related\n\n- [Config File](option-config-file.md) - Configuration options\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [CLI](reference-cli.md) - Command-line interface\n- [Plugins](advanced-plugins.md) - Plugin system\n",".agents/skills/tsdown/references/advanced-rolldown-options.md":"# Customizing Rolldown Options\n\nPass options directly to the underlying Rolldown bundler.\n\n## Overview\n\ntsdown uses [Rolldown](https://rolldown.rs) as its core bundling engine. You can override Rolldown's input and output options directly for fine-grained control.\n\n**Warning:** You should be familiar with Rolldown's behavior before overriding options. Refer to the [Rolldown Config Options](https://rolldown.rs/reference/InputOptions.input) documentation.\n\n## Input Options\n\n### Using an Object\n\n```ts\nexport default defineConfig({\n inputOptions: {\n cwd: './custom-directory',\n },\n})\n```\n\n### Using a Function\n\nDynamically modify options based on the output format:\n\n```ts\nexport default defineConfig({\n inputOptions(inputOptions, format) {\n inputOptions.cwd = './custom-directory'\n return inputOptions\n },\n})\n```\n\n## Output Options\n\n### Using an Object\n\n```ts\nexport default defineConfig({\n outputOptions: {\n legalComments: 'inline',\n },\n})\n```\n\n### Using a Function\n\n```ts\nexport default defineConfig({\n outputOptions(outputOptions, format) {\n if (format === 'esm') {\n outputOptions.legalComments = 'inline'\n }\n return outputOptions\n },\n})\n```\n\n## Common Use Cases\n\n### Preserve Legal Comments\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outputOptions: {\n legalComments: 'inline',\n },\n})\n```\n\n### Custom Working Directory\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n inputOptions: {\n cwd: './packages/my-lib',\n },\n})\n```\n\n### Format-Specific Options\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outputOptions(outputOptions, format) {\n if (format === 'esm') {\n outputOptions.legalComments = 'inline'\n }\n return outputOptions\n },\n})\n```\n\n## When to Use\n\n- When tsdown doesn't expose a specific Rolldown option\n- For format-specific Rolldown customizations\n- For advanced bundling scenarios\n\n## Tips\n\n1. **Read Rolldown docs** before overriding options\n2. **Use functions** for format-specific customization\n3. **Test thoroughly** when overriding defaults\n4. **Prefer tsdown options** when available (e.g., use `minify` instead of setting it via `outputOptions`)\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [Config File](option-config-file.md) - Configuration options\n",".agents/skills/tsdown/references/guide-getting-started.md":"# Getting Started\n\nQuick guide to installing and using tsdown for the first time.\n\n## Installation\n\nInstall tsdown as a development dependency:\n\n```bash\npnpm add -D tsdown\n\n# Optionally install TypeScript if not using isolatedDeclarations\npnpm add -D typescript\n```\n\n**Requirements:**\n- Node.js 22.18.0 or higher **to run tsdown** (build-time only)\n- Experimental support for Deno and Bun\n\n> [!NOTE]\n> The Node.js 22.18+ requirement only applies to the environment that runs `tsdown` itself. The **bundled output** can target much lower Node.js versions via the [`target`](./option-target.md) option, so libraries built with tsdown are not locked to Node.js 22+ at runtime.\n>\n> If your package needs to support Node.js 18 / 20, the recommended workflow is to **build with Node.js 22+ in CI**, then **test the built output (or the packed tarball) against the lower Node.js versions** you intend to support.\n\n## Quick Start Templates\n\nUse `create-tsdown` CLI for instant setup:\n\n```bash\npnpm create tsdown@latest\n```\n\nProvides templates for:\n- Pure TypeScript libraries\n- React component libraries\n- Vue component libraries\n- Ready-to-use configurations\n\n## First Bundle\n\n### 1. Create Source Files\n\n```ts\n// src/index.ts\nimport { hello } from './hello.ts'\nhello()\n\n// src/hello.ts\nexport function hello() {\n console.log('Hello tsdown!')\n}\n```\n\n### 2. Create Config File\n\n```ts\n// tsdown.config.ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n})\n```\n\n### 3. Run Build\n\n```bash\n./node_modules/.bin/tsdown\n```\n\nOutput: `dist/index.mjs`\n\n### 4. Test Output\n\n```bash\nnode dist/index.mjs\n# Output: Hello tsdown!\n```\n\n## Add to npm Scripts\n\n```json\n{\n \"scripts\": {\n \"build\": \"tsdown\"\n }\n}\n```\n\nRun with:\n\n```bash\npnpm build\n```\n\n## CLI Commands\n\n```bash\n# Check version\ntsdown --version\n\n# View help\ntsdown --help\n\n# Build with watch mode\ntsdown --watch\n\n# Build with specific format\ntsdown --format esm,cjs\n\n# Generate type declarations\ntsdown --dts\n```\n\n## Basic Configurations\n\n### TypeScript Library (ESM + CJS)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### Browser Library (IIFE)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n globalName: 'MyLib',\n platform: 'browser',\n minify: true,\n})\n```\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n## Using Plugins\n\nAdd Rolldown, Rollup, or Unplugin plugins:\n\n```ts\nimport SomePlugin from 'some-plugin'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [SomePlugin()],\n})\n```\n\n## Watch Mode\n\nEnable automatic rebuilds on file changes:\n\n```bash\ntsdown --watch\n# or\ntsdown -w\n```\n\n## Next Steps\n\n- Configure [entry points](option-entry.md) with glob patterns\n- Set up [multiple output formats](option-output-format.md)\n- Enable [type declaration generation](option-dts.md)\n- Explore [plugins](advanced-plugins.md) for extended functionality\n- Read [migration guide](guide-migrate-from-tsup.md) if coming from tsup\n",".agents/skills/tsdown/references/guide-introduction.md":"# Introduction\n\n**tsdown** is _The Elegant Library Bundler_ — a fast, simple bundler for TypeScript and JavaScript libraries powered by Rolldown (Rust-based).\n\n## Why tsdown?\n\nBuilt on [Rolldown](https://rolldown.rs), tsdown provides a complete out-of-the-box solution for library authors:\n\n- **Simplified Configuration**: Sensible defaults for library development, minimal boilerplate\n- **Library-Specific Features**: Auto TypeScript declarations, multiple output formats, package validation\n- **Future-Ready**: Official Rolldown project, foundation for Rolldown Vite's Library Mode\n\n## Plugin Ecosystem\n\nSupports the full Rolldown plugin ecosystem plus most Rollup plugins. See [Plugins](advanced-plugins.md).\n\n## What Can It Bundle?\n\n- **TypeScript/JavaScript**: `.ts`, `.js` with modern syntax\n- **TypeScript Declarations**: Auto-generate `.d.ts` files\n- **Multiple Formats**: `esm`, `cjs`, `iife`, `umd`\n- **Assets**: `.json`, `.wasm`, CSS files\n- Built-in tree shaking, minification, and source maps\n\n## Key Differences from Rolldown\n\ntsdown wraps Rolldown with library-specific features:\n- Auto-external `dependencies`, `peerDependencies`, and `optionalDependencies` from `package.json`\n- DTS generation\n- `package.json` exports field generation\n- Watch mode with keyboard shortcuts\n- CSS preprocessing pipeline\n- Executable bundling (SEA)\n\n## Prior Arts\n\nInspired by: Rollup, esbuild, tsup, unbuild. Powered by Rolldown.\n\n## Related\n\n- [Getting Started](guide-getting-started.md) - Installation and first build\n- [Migrate from tsup](guide-migrate-from-tsup.md) - Migration guide\n",".agents/skills/tsdown/references/guide-migrate-from-tsup.md":"# Migrate from tsup\n\nMigration guide for switching from tsup to tsdown.\n\n## Overview\n\ntsdown is built on Rolldown (Rust-based) vs tsup's esbuild, providing faster and more powerful bundling while maintaining compatibility.\n\n## Automatic Migration\n\n### Single Package\n\n```bash\nnpx tsdown-migrate\n```\n\n### Monorepo\n\n```bash\n# Using glob patterns\nnpx tsdown-migrate packages/*\n\n# Multiple directories\nnpx tsdown-migrate packages/foo packages/bar\n```\n\n### Migration Options\n\n- `[...dirs]` - Directories to migrate (supports globs)\n- `--dry-run` or `-d` - Preview changes without modifying files\n- `--yes` or `-y` - Skip confirmation (required in non-interactive environments)\n- `--package-manager ` - Override package manager auto-detection\n- `--no-install` - Skip dependency installation\n\nFor non-interactive callers that install dependencies separately:\n\n```bash\nnpx tsdown-migrate --yes --no-install\n```\n\nWhen installation is enabled, the tool detects the package manager from the\nproject's `packageManager` field or lockfile. If detection fails without a TTY,\npass `--package-manager ` or `--no-install`.\n\n**Important:** Commit your changes before running migration.\n\n## Key Differences\n\n### Default Values\n\n| Option | tsup | tsdown |\n|--------|------|--------|\n| `format` | `['cjs']` | `['esm']` |\n| `clean` | `false` | `true` |\n| `dts` | `false` | Auto-enabled if `types`/`typings` in package.json |\n| `target` | Manual | Auto-read from `engines.node` in package.json |\n\n### Option Renames\n\n| tsup | tsdown |\n|------|--------|\n| `entryPoints` | `entry` |\n| `cjsInterop` | `cjsDefault` |\n| `esbuildPlugins` | `plugins` |\n| `outExtension` | `outExtensions` |\n| `skipNodeModulesBundle` | `deps: { neverBundle: true }` |\n| `publicDir` | `copy` |\n| `bundle: false` | `unbundle: true` |\n| `removeNodeProtocol: true` | `nodeProtocol: 'strip'` |\n| `injectStyle: true` | `css: { inject: true }` |\n\nThe old names were accepted (with deprecation warnings) up to tsdown v0.22.14 and have been removed since — v0.23+ silently ignores them, so a leftover tsup option won't error. Migrate in two stages: install `tsdown@0.22.14` first and resolve every deprecation warning (a warning-free build proves the mapping is complete), then upgrade to the latest version. The `tsdown-migrate` tool installs v0.22.14 for this reason.\n\n### Deprecated but Compatible Options\n\nThese tsup options still work but emit deprecation warnings and will be removed in a future version — migrate them immediately:\n\n| tsup (deprecated) | tsdown (preferred) |\n|-------------------|--------------------|\n| `external: [...]` | `deps: { neverBundle: [...] }` |\n| `noExternal: [...]` | `deps: { alwaysBundle: [...] }` |\n\ntsdown also adds `deps.onlyBundle` for whitelisting allowed bundled packages.\n\n### Unsupported Options\n\n| Option | Status | Alternative |\n|--------|--------|-------------|\n| `splitting: false` | Always enabled | Code splitting cannot be disabled |\n| `metafile` | Not available | Use `devtools: true` for bundle analysis via Vite DevTools |\n| `swc` | Not supported | tsdown uses oxc for transformation (built-in) |\n| `experimentalDts` | Superseded | Use the `dts` option instead |\n| `legacyOutput` | Not supported | No alternative |\n| `plugins` (tsup experimental) | Incompatible | Migrate to Rolldown plugins |\n\n### Plugin System\n\ntsdown uses Rolldown plugins instead of esbuild plugins. If you use unplugin plugins, update the import path:\n\n```ts\n// Before (tsup)\nimport plugin from 'unplugin-example/esbuild'\n// After (tsdown)\nimport plugin from 'unplugin-example/rolldown'\n```\n\n### Output Filename Differences\n\nFor IIFE builds, `tsdown` emits `[name].iife.js`; `tsup` commonly emitted `[name].global.js`. `outExtensions` customizes extensions or suffixes, but it does not remove `.iife` or `.umd`. Use `outputOptions.entryFileNames: '[name].global.js'` to preserve old IIFE filenames.\n\n### New Features in tsdown\n\n#### Node Protocol Control\n\n```ts\nexport default defineConfig({\n nodeProtocol: true, // Add node: prefix (fs → node:fs)\n nodeProtocol: 'strip', // Remove node: prefix (node:fs → fs)\n nodeProtocol: false, // Keep as-is (default)\n})\n```\n\n#### Better Workspace Support\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*', // Build all packages\n})\n```\n\n#### Other tsdown-Exclusive Features\n\n- **`exports`**: Auto-generate the `exports` field in `package.json` with `exports: true`\n- **`publint`** / **`attw`**: Validate your package for common issues and type correctness\n- **`exe`**: Bundle as a Node.js standalone executable (SEA) with `exe: true`\n- **`devtools`**: Vite DevTools integration for bundle analysis with `devtools: true`\n- **`hooks`**: Lifecycle hooks (`build:prepare`, `build:before`, `build:done`)\n- **`css`**: Full CSS pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, and code splitting\n- **`globImport`**: Support for `import.meta.glob` (Vite-style glob imports)\n\n## Migration Checklist\n\n1. **Backup your code** - Commit all changes\n2. **Run migration tool** - `npx tsdown-migrate`\n3. **Review changes** - Check modified config files\n4. **Update scripts** - Change `tsup` to `tsdown` in package.json\n5. **Test build** - Run `pnpm build` to verify\n6. **Adjust config** - Fine-tune based on your needs\n\n## Common Migration Patterns\n\n### Basic Library\n\n**Before (tsup):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs', 'esm'],\n dts: true,\n})\n```\n\n**After (tsdown):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'], // ESM now default\n dts: true,\n clean: true, // Now enabled by default\n})\n```\n\n### With Custom Target\n\n**Before (tsup):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n target: 'es2020',\n})\n```\n\n**After (tsdown):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n // target auto-reads from package.json engines.node\n // Or override explicitly:\n target: 'es2020',\n})\n```\n\n### CLI Scripts\n\n**Before (package.json):**\n```json\n{\n \"scripts\": {\n \"build\": \"tsup\",\n \"dev\": \"tsup --watch\"\n }\n}\n```\n\n**After (package.json):**\n```json\n{\n \"scripts\": {\n \"build\": \"tsdown\",\n \"dev\": \"tsdown --watch\"\n }\n}\n```\n\n## Feature Compatibility\n\n### Supported tsup Features\n\nMost tsup features are supported:\n- ✅ Multiple entry points\n- ✅ Multiple formats (ESM, CJS, IIFE, UMD)\n- ✅ TypeScript declarations\n- ✅ Source maps\n- ✅ Minification\n- ✅ Watch mode\n- ✅ External dependencies\n- ✅ Tree shaking\n- ✅ Shims\n- ✅ Plugins (Rollup compatible)\n\n### Missing Features\n\nSome tsup features are not yet available. Check [GitHub issues](https://github.com/rolldown/tsdown/issues) for status and request features.\n\n## Troubleshooting\n\n### Build Fails After Migration\n\n1. **Check Node.js version** - Requires Node.js 22.18.0+ to run tsdown itself. The bundled output can still target lower Node.js versions via `target`; if you need to support Node.js 18 / 20, build with Node.js 22+ in CI and test the produced output (or packed tarball) on the lower versions.\n2. **Install TypeScript** - Required for DTS generation\n3. **Review config changes** - Ensure format and options are correct\n4. **Check dependencies** - Verify all dependencies are installed\n\n### Different Output\n\n- **Format order** - tsdown defaults to ESM first\n- **Clean behavior** - tsdown cleans outDir by default\n- **Target** - tsdown auto-detects from package.json\n\n### Performance Issues\n\ntsdown should be faster than tsup. If not:\n1. Enable `isolatedDeclarations` for faster DTS generation\n2. Check for large dependencies being bundled\n3. Use `deps.neverBundle: true` if needed\n\n## Getting Help\n\n- [GitHub Issues](https://github.com/rolldown/tsdown/issues) - Report bugs or request features\n- [Documentation](https://tsdown.dev) - Full documentation\n- [Migration Tool](https://github.com/rolldown/tsdown/tree/main/packages/migrate) - Source code\n\n## Acknowledgements\n\ntsdown is heavily inspired by tsup and incorporates parts of its codebase. Thanks to [@egoist](https://github.com/egoist) and the tsup community.\n",".agents/skills/tsdown/references/option-cjs-default.md":"# CJS Default Export\n\nControl how default exports are handled in CommonJS output.\n\n## Overview\n\nThe `cjsDefault` option improves compatibility when generating CommonJS **entry** modules. When enabled (default), entry modules with only a single default export use `module.exports = ...` instead of `exports.default = ...`.\n\n## Type\n\n```ts\ncjsDefault?: boolean // default: true\n```\n\n## Basic Usage\n\n### Enabled (Default)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n cjsDefault: true, // default behavior\n})\n```\n\n### Disabled\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n cjsDefault: false,\n})\n```\n\n## How It Works\n\n### With `cjsDefault: true` (Default)\n\nWhen your module has **only a single default export**, tsdown transforms:\n\n**Source:**\n```ts\n// src/index.ts\nexport default function greet() {\n console.log('Hello, world!')\n}\n```\n\n**Generated CJS:**\n```js\n// dist/index.cjs\nfunction greet() {\n console.log('Hello, world!')\n}\nmodule.exports = greet\n```\n\n**Generated Declaration:**\n```ts\n// dist/index.d.cts\ndeclare function greet(): void\nexport = greet\n```\n\nThis allows consumers to use `const greet = require('your-module')` directly.\n\n### With `cjsDefault: false`\n\nThe default export stays as `exports.default`:\n\n```js\n// dist/index.cjs\nfunction greet() {\n console.log('Hello, world!')\n}\nexports.default = greet\n```\n\nConsumers need `require('your-module').default`.\n\n## Entry Modules Only\n\n`cjsDefault` only applies to **explicit entry modules**. In [unbundle mode](option-unbundle.md), imported modules that are emitted as non-entry chunks keep named CJS exports such as `exports.default`. CJS is considered legacy and is supported in maintenance-only mode, so this behavior will not be extended to non-entry chunks.\n\nIf every source module is intended to be consumed independently, include all of them as entries:\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts'],\n root: 'src',\n format: 'cjs',\n unbundle: true,\n})\n```\n\n## When to Disable\n\n- When your module has both default and named exports\n- When you need consistent `exports.default` behavior\n- When consumers always use ESM imports\n\n## Tips\n\n1. **Leave enabled** for most libraries (default `true`)\n2. **Disable** if you have both default and named exports and need consistent behavior\n3. **Test CJS consumers** to verify compatibility\n\n## Related Options\n\n- [Output Format](option-output-format.md) - Module formats\n- [Shims](option-shims.md) - ESM/CJS compatibility\n",".agents/skills/tsdown/references/option-cleaning.md":"# Output Directory Cleaning\n\nControl how the output directory is cleaned before builds.\n\n## Overview\n\nBy default, tsdown **cleans the output directory** before each build to remove stale files from previous builds.\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Clean enabled (default)\ntsdown\n\n# Disable cleaning\ntsdown --no-clean\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n clean: true, // Default\n})\n```\n\n## Behavior\n\n### With Cleaning (Default)\n\nBefore each build:\n1. All files in `outDir` are removed\n2. Fresh build starts with empty directory\n3. Only current build outputs remain\n\n**Benefits:**\n- No stale files\n- Predictable output\n- Clean slate each build\n\n### Without Cleaning\n\nBuild outputs are added to existing files:\n\n```ts\nexport default defineConfig({\n clean: false,\n})\n```\n\n**Use when:**\n- Multiple builds to same directory\n- Incremental builds\n- Preserving other files\n- Watch mode (faster rebuilds)\n\n## Common Patterns\n\n### Production Build\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n clean: true, // Ensure clean output\n minify: true,\n})\n```\n\n### Development Mode\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n clean: !options.watch, // Don't clean in watch mode\n sourcemap: options.watch,\n}))\n```\n\n### Multiple Builds\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true, // Clean once\n },\n {\n entry: ['src/cli.ts'],\n outDir: 'dist',\n clean: false, // Don't clean, add to same dir\n },\n])\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n clean: true, // Clean each package's dist\n})\n```\n\n### Preserve Static Files\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n clean: false, // Keep manually added files\n outDir: 'dist',\n})\n\n// Manually copy files first\n// Then run tsdown --no-clean\n```\n\n## Clean Patterns\n\n### Selective Cleaning\n\n```ts\nimport { rmSync } from 'fs'\n\nexport default defineConfig({\n clean: false, // Disable auto clean\n hooks: {\n 'build:prepare': () => {\n // Custom cleaning logic\n rmSync('dist/*.js', { force: true })\n // Keep other files\n },\n },\n})\n```\n\n### Clean Specific Directories\n\n```ts\nexport default defineConfig({\n clean: false,\n hooks: {\n 'build:prepare': async () => {\n const { rm } = await import('fs/promises')\n // Only clean specific subdirectories\n await rm('dist/esm', { recursive: true, force: true })\n await rm('dist/cjs', { recursive: true, force: true })\n // Keep dist/types\n },\n },\n})\n```\n\n## Watch Mode Behavior\n\nIn watch mode, cleaning behavior is important:\n\n### Clean on First Build Only\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n watch: options.watch,\n clean: !options.watch, // Only clean initial build\n}))\n```\n\n**Result:**\n- First build: Clean\n- Subsequent rebuilds: Incremental\n\n### Always Clean\n\n```ts\nexport default defineConfig({\n watch: true,\n clean: true, // Clean every rebuild\n})\n```\n\n**Trade-off:** Slower rebuilds, but always fresh output.\n\n## Tips\n\n1. **Leave enabled** for production builds\n2. **Disable in watch mode** for faster rebuilds\n3. **Use multiple configs** carefully with cleaning\n4. **Custom clean logic** via hooks if needed\n5. **Be cautious** - cleaning removes ALL files in outDir\n6. **Test cleaning** - ensure no important files are lost\n\n## Troubleshooting\n\n### Important Files Deleted\n\n- Don't put non-build files in outDir\n- Use separate directory for static files\n- Disable cleaning and manage manually\n\n### Stale Files in Output\n\n- Enable cleaning: `clean: true`\n- Or manually remove before build\n\n### Slow Rebuilds in Watch\n\n- Disable cleaning in watch mode\n- Use incremental builds\n\n## CLI Examples\n\n```bash\n# Default (clean enabled)\ntsdown\n\n# Disable cleaning\ntsdown --no-clean\n\n# Watch mode without cleaning\ntsdown --watch --no-clean\n\n# Multiple formats with cleaning\ntsdown --format esm,cjs --clean\n```\n\n## Examples\n\n### Safe Production Build\n\n```bash\n# Clean before build\nrm -rf dist\ntsdown --clean\n```\n\n### Incremental Development\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n watch: true,\n clean: false, // Faster rebuilds\n sourcemap: true,\n})\n```\n\n### Multi-Stage Build\n\n```ts\n// Stage 1: Clean and build main\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true,\n },\n {\n entry: ['src/utils.ts'],\n outDir: 'dist',\n clean: false, // Add to same directory\n },\n])\n```\n\n## Related Options\n\n- [Output Directory](option-output-directory.md) - Configure outDir\n- [Watch Mode](option-watch-mode.md) - Development workflow\n- [Hooks](advanced-hooks.md) - Custom clean logic\n- [Entry](option-entry.md) - Entry points\n",".agents/skills/tsdown/references/option-config-file.md":"# Configuration File\n\nCentralize and manage build settings with a configuration file.\n\n## Overview\n\ntsdown searches for config files automatically in the current directory and parent directories.\n\n## Supported File Names\n\ntsdown looks for these files (in order):\n- `tsdown.config.ts`\n- `tsdown.config.mts`\n- `tsdown.config.cts`\n- `tsdown.config.js`\n- `tsdown.config.mjs`\n- `tsdown.config.cjs`\n- `tsdown.config.json`\n- `tsdown.config`\n- `package.json` (in `tsdown` field)\n\n## Basic Configuration\n\n### TypeScript Config\n\n```ts\n// tsdown.config.ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### JavaScript Config\n\n```js\n// tsdown.config.js\nexport default {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n}\n```\n\n### JSON Config\n\n```json\n// tsdown.config.json\n{\n \"entry\": [\"src/index.ts\"],\n \"format\": [\"esm\", \"cjs\"],\n \"dts\": true\n}\n```\n\n### Package.json Config\n\n```json\n// package.json\n{\n \"name\": \"my-library\",\n \"tsdown\": {\n \"entry\": [\"src/index.ts\"],\n \"format\": [\"esm\", \"cjs\"],\n \"dts\": true\n }\n}\n```\n\n## Multiple Configurations\n\nBuild multiple outputs with different settings:\n\n```ts\nexport default defineConfig([\n {\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n platform: 'node',\n dts: true,\n },\n {\n entry: 'src/browser.ts',\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n minify: true,\n },\n])\n```\n\nEach configuration runs as a separate build.\n\n## Dynamic Configuration\n\nUse a function for conditional config:\n\n```ts\nexport default defineConfig((options) => {\n const isDev = options.watch\n\n return {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n clean: !isDev,\n }\n})\n```\n\nAvailable options:\n- `watch` - Whether watch mode is enabled\n- Other CLI flags passed to config\n\n## Config Loaders\n\nControl how TypeScript config files are loaded:\n\n### Auto Loader (Default)\n\nUses native TypeScript support if available, otherwise falls back to `unrun`:\n\n```bash\ntsdown # Uses auto loader\n```\n\n### Native Loader\n\nUses runtime's native TypeScript support (Node.js 22.18.0+, Bun, Deno):\n\n```bash\ntsdown --config-loader native\n```\n\n### tsx Loader\n\nUses [tsx](https://tsx.is/) library for loading via its tsImport API. Note: `tsx` is an optional peer dependency — install it manually first.\n\n```bash\npnpm add -D tsx\ntsdown --config-loader tsx\n```\n\n### Unrun Loader\n\nUses [unrun](https://gugustinette.github.io/unrun/) library for loading. Note: `unrun` is an optional peer dependency — install it manually first.\n\n```bash\npnpm add -D unrun\ntsdown --config-loader unrun\n```\n\n**Tip:** Use `tsx` or `unrun` loader if you need to load TypeScript configs without file extensions in Node.js.\n\n## Custom Config Path\n\nSpecify a custom config file location:\n\n```bash\ntsdown --config ./configs/build.config.ts\n# or\ntsdown -c custom-config.ts\n```\n\n## Disable Config File\n\nIgnore config files and use CLI options only:\n\n```bash\ntsdown --no-config src/index.ts --format esm\n```\n\n## Extend Vite/Vitest Config (Experimental)\n\nReuse existing Vite or Vitest configurations:\n\n```bash\n# Extend vite.config.*\ntsdown --from-vite\n\n# Extend vitest.config.*\ntsdown --from-vite vitest\n```\n\n**Note:** Only specific options like `resolve` and `plugins` are reused. Test thoroughly as this feature is experimental.\n\n## Workspace / Monorepo\n\nBuild multiple packages with a single config:\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nEach package directory matching the glob pattern will be built with the same configuration.\n\n## Common Patterns\n\n### Library with Multiple Builds\n\n```ts\nexport default defineConfig([\n // Node.js build\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n platform: 'node',\n dts: true,\n },\n // Browser build\n {\n entry: ['src/browser.ts'],\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n },\n])\n```\n\n### Development vs Production\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !options.watch,\n sourcemap: options.watch ? true : false,\n clean: !options.watch,\n}))\n```\n\n### Monorepo Root Config\n\n```ts\n// Root tsdown.config.ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n // Shared config for all packages\n})\n```\n\n### Per-Package Override\n\n```ts\n// packages/special/tsdown.config.ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm'], // Override: only ESM\n platform: 'browser', // Override: browser only\n})\n```\n\n## Config Precedence\n\nWhen multiple configs exist:\n\n1. CLI options (highest priority)\n2. Config file specified with `--config`\n3. Auto-discovered config files\n4. Package.json `tsdown` field\n5. Default values\n\n## Tips\n\n1. **Use TypeScript config** for type checking and autocomplete\n2. **Use defineConfig** helper for better DX\n3. **Export arrays** for multiple build configurations\n4. **Use functions** for dynamic/conditional configs\n5. **Keep configs simple** - prefer convention over configuration\n6. **Use workspace** for monorepo builds\n7. **Test experimental features** thoroughly before production use\n\n## Related Options\n\n- [Entry](option-entry.md) - Configure entry points\n- [Output Format](option-output-format.md) - Output formats\n- [Watch Mode](option-watch-mode.md) - Watch mode configuration\n",".agents/skills/tsdown/references/option-copy.md":"# Copy Files\n\nCopy static files and directories into the build output.\n\n## Overview\n\nThe `copy` option copies assets that should be distributed without being processed by the bundler — images, fonts, license files, etc.\n\n## Basic Usage\n\n### CLI\n\n```bash\ntsdown --copy public\n```\n\nWith the default `outDir` of `dist`, `public/favicon.svg` is copied to `dist/public/favicon.svg`.\n\n### Config File\n\n```ts\nexport default defineConfig({\n copy: 'public',\n})\n```\n\nMultiple paths, glob patterns, or object entries in an array:\n\n```ts\nexport default defineConfig({\n copy: [\n 'LICENSE',\n {\n from: ['public/**/*', '!public/**/*.map'],\n to: 'dist/assets',\n flatten: false,\n },\n ],\n})\n```\n\nGlob patterns support negation with a leading `!`.\n\n**Note:** Relative source and destination paths are resolved from the project root (`cwd`), not from `outDir`.\n\n## Object Options\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `from` | `string \\| string[]` | Required | Source path or glob pattern; arrays can include negated patterns |\n| `to` | `string` | `outDir` | Destination path, resolved from the project root |\n| `flatten` | `boolean` | `true` | Place matched files directly in `to`. Set `false` to preserve the directory structure below the first segment |\n| `rename` | `string \\| ((name, extension, fullPath) => string)` | — | Change the destination name. Callback receives the extension without a leading dot and the absolute path |\n| `verbose` | `boolean` | `false` | Log each copied source and destination |\n\n### Preserve Directory Structure\n\n```ts\nexport default defineConfig({\n copy: {\n from: 'assets/**/*',\n to: 'dist/public',\n flatten: false,\n },\n})\n```\n\n`assets/fonts/inter.woff2` → `dist/public/fonts/inter.woff2`.\n\n### Rename Copied Items\n\n```ts\nexport default defineConfig({\n copy: [\n { from: 'src/file.txt', to: 'dist', rename: 'file.md' },\n {\n from: 'src/file.txt',\n to: 'dist',\n rename: (name, extension) => `${name}-renamed.${extension}`,\n },\n ],\n})\n```\n\nCreates `dist/file.md` and `dist/file-renamed.txt`.\n\n## Dynamic Configuration\n\n`copy` can be a sync or async callback receiving the resolved tsdown config:\n\n```ts\nexport default defineConfig({\n copy: ({ outDir }) => ({\n from: ['assets/**/*', '!assets/**/*.map'],\n to: `${outDir}/assets`,\n flatten: false,\n }),\n})\n```\n\n## Build and Watch Behavior\n\n- Copying runs after the bundle output is produced; files are copied without passing through Rolldown transforms.\n- A top-level `copy` option runs only once for a multi-format build; a format-specific override can define `copy` again for that format.\n- In watch mode, matched source files are watched as build dependencies — changing one triggers a rebuild and copies the current files again.\n\n## Related Options\n\n- [Output Directory](option-output-directory.md) - Where output goes\n- [Cleaning](option-cleaning.md) - Output directory cleanup\n- [Watch Mode](option-watch-mode.md) - Watch mode behavior\n",".agents/skills/tsdown/references/option-css.md":"# CSS Support\n\n**Status: Experimental — API and behavior may change.**\n\nConfigure CSS handling including preprocessors, syntax lowering, minification, and code splitting.\n\n## Getting Started\n\nAll CSS support in `tsdown` is provided by the `@tsdown/css` package. Install it to enable CSS handling:\n\n```bash\nnpm install -D @tsdown/css\n```\n\nWhen `@tsdown/css` is installed, CSS processing is automatically enabled. Without it, encountering CSS files will result in an error.\n\n## CSS Import\n\nImport `.css` files from TypeScript/JavaScript — CSS is extracted into separate `.css` assets:\n\n```ts\n// src/index.ts\nimport './style.css'\nexport function greet() { return 'Hello' }\n```\n\nOutput: `index.mjs` + `index.css`\n\n### `@import` Inlining\n\nCSS `@import` statements are resolved and inlined automatically. No separate output files produced.\n\n### Inline CSS (`?inline`)\n\nAppend `?inline` to return processed CSS as a JS string instead of emitting a `.css` file:\n\n```ts\nimport './style.css' // → .css file\nimport css from './theme.css?inline' // → JS string\n```\n\nWorks with preprocessors too (`./foo.scss?inline`). Goes through full pipeline (preprocessors, @import inlining, lowering, minification). Tree-shakeable (`moduleSideEffects: false`).\n\n## CSS Pre-processors\n\nBuilt-in support for Sass, Less, and Stylus. Install the preprocessor:\n\n```bash\n# Sass (either one)\nnpm install -D sass-embedded # recommended, faster\nnpm install -D sass\n\n# Less\nnpm install -D less\n\n# Stylus\nnpm install -D stylus\n```\n\nThen import directly:\n\n```ts\nimport './style.scss'\nimport './theme.less'\nimport './global.styl'\n```\n\n### Preprocessor Options\n\n```ts\nexport default defineConfig({\n css: {\n preprocessorOptions: {\n scss: {\n additionalData: `$brand-color: #ff7e17;`,\n },\n less: {\n math: 'always',\n },\n stylus: {\n define: { '$brand-color': '#ff7e17' },\n },\n },\n },\n})\n```\n\n### `additionalData`\n\nInject code at the beginning of every preprocessor file:\n\n```ts\n// String form\nscss: {\n additionalData: `@use \"src/styles/variables\" as *;`,\n}\n\n// Function form\nscss: {\n additionalData: (source, filename) => {\n if (filename.includes('theme')) return source\n return `@use \"src/styles/variables\" as *;\\n${source}`\n },\n}\n```\n\n## CSS Minification\n\n```ts\nexport default defineConfig({\n css: {\n minify: true,\n },\n})\n```\n\nPowered by Lightning CSS.\n\n## CSS Target\n\nOverride the top-level `target` specifically for CSS:\n\n```ts\nexport default defineConfig({\n target: 'node18',\n css: {\n target: 'chrome90', // CSS-specific target\n },\n})\n```\n\nSet `css.target: false` to disable CSS syntax lowering entirely.\n\n## CSS Transformer\n\n`css.transformer` controls mutually exclusive CSS processing paths:\n\n- `'lightningcss'` (default): `@import` via Lightning CSS `bundleAsync()`, no PostCSS.\n- `'postcss'`: `@import` via `postcss-import`, PostCSS plugins applied, Lightning CSS for final transform only.\n\n```ts\nexport default defineConfig({\n css: {\n transformer: 'postcss',\n },\n})\n```\n\n### PostCSS Options\n\n```ts\nexport default defineConfig({\n css: {\n transformer: 'postcss',\n postcss: {\n plugins: [require('autoprefixer')],\n },\n // Or: postcss: './config' — path to search for postcss.config.js\n },\n})\n```\n\nAuto-detects PostCSS config from project root when `transformer` is `'postcss'` and `css.postcss` is omitted.\n\n## Lightning CSS (Syntax Lowering)\n\nInstall `lightningcss` to enable CSS syntax lowering based on your `target`:\n\n```bash\nnpm install -D lightningcss\n```\n\nWhen `target` is set (e.g., `target: 'chrome108'`), modern CSS features are automatically downleveled:\n\n```css\n/* Input */\n.foo { & .bar { color: red } }\n\n/* Output (chrome108) */\n.foo .bar { color: red }\n```\n\n### Custom Lightning CSS Options\n\n```ts\nimport { Features } from 'lightningcss'\n\nexport default defineConfig({\n css: {\n lightningcss: {\n targets: { chrome: 100 << 16 },\n include: Features.Nesting,\n },\n },\n})\n```\n\n`css.lightningcss.targets` takes precedence over both `target` and `css.target` for CSS.\n\n## CSS Modules\n\nFiles with `.module.css` (and `.module.scss`, `.module.less`, etc.) are treated as CSS modules — class names are scoped and exported as JS:\n\n```ts\nimport styles from './app.module.css'\nconsole.log(styles.title) // \"scoped_title_hash\"\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n css: {\n modules: {\n scopeBehaviour: 'local', // 'local' (default) | 'global'\n generateScopedName: '[hash]_[local]', // Lightning CSS pattern string\n localsConvention: 'camelCase', // 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly'\n },\n },\n})\n```\n\nSet `css.modules: false` to disable. Function-form `generateScopedName` requires `transformer: 'postcss'`.\n\n`localsConvention` also accepts a function compatible with Vite and\n`postcss-modules`:\n\n```ts\nexport default defineConfig({\n css: {\n modules: {\n localsConvention: (\n originalClassName,\n generatedClassName,\n inputFile,\n ) => originalClassName.replaceAll(/-([a-z0-9])/g, (_, c) => c.toUpperCase()),\n },\n },\n})\n```\n\nThe function form works with both CSS transformers and returns the JavaScript\nexport key.\n\n### Optional Dependencies (PostCSS path)\n\n```bash\nnpm install -D postcss postcss-modules\n```\n\n## Code Splitting\n\n### Merged (Default)\n\nAll CSS merged into a single file (default: `style.css`).\n\n```ts\nexport default defineConfig({\n css: {\n fileName: 'my-library.css', // Custom name (default: 'style.css')\n },\n})\n```\n\n### Per-Chunk Splitting\n\n```ts\nexport default defineConfig({\n css: {\n splitting: true, // Each JS chunk gets a corresponding .css file\n },\n})\n```\n\n## Preserving CSS Imports (`css.inject`)\n\nWhen enabled, JS output preserves `import` statements pointing to emitted CSS files. Consumers auto-import CSS alongside JS:\n\n```ts\nexport default defineConfig({\n css: {\n inject: true,\n },\n})\n```\n\n## PostCSS Optional Peer Dependencies\n\nWhen using `transformer: 'postcss'`, install these as needed:\n\n| Package | Purpose | Required When |\n|---------|---------|---------------|\n| `postcss` | Core PostCSS engine | Always (with `transformer: 'postcss'`) |\n| `postcss-import` | Resolve/inline `@import` | CSS uses `@import` |\n| `postcss-modules` | CSS modules (scoped classes) | Using `.module.css` files |\n\n```bash\nnpm install -D postcss postcss-import postcss-modules\n```\n\nAll declared as optional peer dependencies of `@tsdown/css`.\n\n## Options Reference\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `css.transformer` | `'postcss' \\| 'lightningcss'` | `'lightningcss'` | CSS processing pipeline |\n| `css.splitting` | `boolean` | `false` | Per-chunk CSS splitting |\n| `css.fileName` | `string` | `'style.css'` | Merged CSS file name |\n| `css.minify` | `boolean` | `false` | CSS minification |\n| `css.modules` | `object \\| false` | `{}` | CSS modules config, or `false` to disable |\n| `css.inject` | `boolean` | `false` | Preserve CSS imports in JS output |\n| `css.target` | `string \\| string[] \\| false` | _from `target`_ | CSS-specific lowering target |\n| `css.postcss` | `string \\| object` | — | PostCSS config path or inline options |\n| `css.preprocessorOptions` | `object` | — | Preprocessor options |\n| `css.lightningcss` | `object` | — | Lightning CSS options |\n\n## Related\n\n- [Target](option-target.md) - Configure syntax lowering targets\n- [Output Format](option-output-format.md) - Module output formats\n",".agents/skills/tsdown/references/option-dependencies.md":"# Dependencies\n\nControl how dependencies are bundled or externalized.\n\n## Overview\n\ntsdown intelligently handles dependencies to keep your library lightweight while ensuring all necessary code is included.\n\n## Default Behavior\n\n### Auto-Externalized\n\nThese are **NOT bundled** by default:\n\n- **`dependencies`** - Installed automatically with your package\n- **`peerDependencies`** - User must install manually\n- **`optionalDependencies`** - May or may not be installed depending on platform/config\n\n### Conditionally Bundled\n\nThese are **bundled ONLY if imported**:\n\n- **`devDependencies`** - Only if actually used in source code\n- **Phantom dependencies** - In node_modules but not in package.json\n\n## Configuration Options\n\nAll dependency options are grouped under the `deps` field:\n\n```ts\nexport default defineConfig({\n deps: {\n neverBundle: ['react', /^@myorg\\//],\n alwaysBundle: ['some-package'],\n onlyBundle: ['cac', 'bumpp'],\n onlyImport: ['cac'],\n resolveDepSubpath: true,\n },\n})\n```\n\n### `deps.neverBundle`\n\nMark dependencies as external (not bundled):\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: [\n 'react', // Single package\n 'react-dom',\n /^@myorg\\//, // Regex pattern (all @myorg/* packages)\n /^lodash/, // All lodash packages\n ],\n },\n})\n```\n\nSet to `true` to externalize ALL dependencies:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: true,\n },\n})\n```\n\n**Result:** Every import that follows npm package naming conventions is externalized as written, without being resolved. This is fast and even works when dependencies are not installed. Subpaths like `my-dep/utils` are preserved exactly unless `resolveDepSubpath` is enabled. Other non-relative imports (`#` subpath imports, path aliases like `~/`) are resolved: they stay external if they resolve into node_modules, and are bundled if they map to local files. Combine with `alwaysBundle` to bundle selected dependencies.\n\n### `deps.alwaysBundle`\n\nForce dependencies to be bundled:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n alwaysBundle: [\n 'some-package', // Bundle this even if in dependencies\n 'vendor-lib',\n ],\n },\n})\n```\n\n### `deps.onlyBundle`\n\nWhitelist of dependencies allowed to be bundled from node_modules. Throws an error if any unlisted dependency is bundled:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n onlyBundle: [\n 'cac', // Allow bundling cac\n 'bumpp', // Allow bundling bumpp\n /^my-utils/, // Regex patterns supported\n ],\n },\n})\n```\n\n**Behavior:**\n- **Array** (`['cac', /^my-/]`): Only matching dependencies can be bundled. Error for others.\n- **`false`**: Suppress all warnings about bundled dependencies.\n- **Not set** (default): Warns if any node_modules dependencies are bundled.\n\n**Note:** Include all sub-dependencies in the list, not just top-level imports.\n\n### `deps.onlyImport`\n\nWhitelist of packages the emitted output is allowed to import at runtime. Throws an error (listing all violations) if any chunk imports an unlisted package:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n onlyImport: [\n 'cac', // Also covers subpath imports like cac/deno\n /^my-utils/, // Regex patterns match the package name\n ],\n },\n})\n```\n\n**Behavior:**\n- Matching is based on the package name; subpath imports (`cac/deno`) match `cac`.\n- Node.js built-in modules are always allowed when `platform` is `node`.\n- Relative imports between code-split chunks are always allowed.\n- Declaration output (`.d.ts`) is checked too.\n\n**Limitation:** ES imports and dynamic `import()` expressions are checked. CJS `require()` calls are not detected.\n\n### `deps.resolveDepSubpath`\n\nBy default, tsdown preserves external dependency subpath imports as written. Enable `resolveDepSubpath` to resolve subpath imports to their actual package-relative paths when a package has no `exports` field. For example, `my-dep/functions/lt` may become `my-dep/functions/lt.js`, and `my-dep/folder` may become `my-dep/folder/index.js`.\n\n```ts\nexport default defineConfig({\n deps: {\n resolveDepSubpath: true, // default: false\n },\n})\n```\n\n## Common Patterns\n\n### React Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.tsx'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n 'react',\n 'react-dom',\n /^react\\//, // react/jsx-runtime, etc.\n ],\n },\n dts: true,\n})\n```\n\n### Utility Library with Shared Deps\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n alwaysBundle: ['lodash-es'],\n },\n dts: true,\n})\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n /^@mycompany\\//, // Don't bundle other workspace packages\n ],\n },\n dts: true,\n})\n```\n\n### CLI Tool (Bundle Everything)\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n format: ['esm'],\n platform: 'node',\n deps: {\n alwaysBundle: [/.*/],\n },\n shims: true,\n})\n```\n\n### Library with Specific Externals\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n 'vue',\n '@vue/runtime-core',\n '@vue/reactivity',\n ],\n },\n dts: true,\n})\n```\n\n## Declaration Files\n\nDependency handling for `.d.ts` files follows the same rules as JavaScript.\n\n### Complex Type Resolution\n\nUse TypeScript resolver for complex third-party types:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n dts: {\n resolver: 'tsc', // Use TypeScript resolver instead of Oxc\n },\n})\n```\n\n**When to use `tsc` resolver:**\n- Types in `@types/*` packages with non-standard naming (e.g., `@types/babel__generator`)\n- Complex type dependencies\n- Issues with default Oxc resolver\n\n**Trade-off:** `tsc` is slower but more compatible.\n\n## CLI Usage\n\n### Never Bundle\n\n```bash\ntsdown --deps.never-bundle react --deps.never-bundle react-dom\ntsdown --deps.never-bundle '/^@myorg\\/.*/'\n```\n\n## Migration from Deprecated Options\n\n| Deprecated Option | New Option |\n|---|---|\n| `external` | `deps.neverBundle` |\n| `noExternal` | `deps.alwaysBundle` |\n\n## Examples by Use Case\n\n### Framework Component\n\n```ts\n// Don't bundle framework\nexport default defineConfig({\n deps: {\n neverBundle: ['vue', 'react', 'solid-js', 'svelte'],\n },\n})\n```\n\n### Standalone App\n\n```ts\n// Bundle everything\nexport default defineConfig({\n deps: {\n alwaysBundle: [/.*/],\n },\n})\n```\n\n### Shared Library\n\n```ts\n// Bundle only specific utils\nexport default defineConfig({\n deps: {\n neverBundle: [/.*/], // External by default\n alwaysBundle: ['tiny-utils'], // Except this one\n },\n})\n```\n\n### Monorepo Package\n\n```ts\n// External workspace packages, bundle utilities\nexport default defineConfig({\n deps: {\n neverBundle: [\n /^@workspace\\//, // Other workspace packages\n 'react',\n 'react-dom',\n ],\n alwaysBundle: [\n 'lodash-es', // Bundle utility libraries\n ],\n },\n})\n```\n\n## Troubleshooting\n\n### Dependency Bundled Unexpectedly\n\nCheck if it's in `devDependencies` and imported. Move to `dependencies`:\n\n```json\n{\n \"dependencies\": {\n \"should-be-external\": \"^1.0.0\"\n }\n}\n```\n\nOr explicitly externalize:\n\n```ts\nexport default defineConfig({\n deps: {\n neverBundle: ['should-be-external'],\n },\n})\n```\n\n### Missing Dependency at Runtime\n\nEnsure it's in `dependencies`, `peerDependencies`, or `optionalDependencies`:\n\n```json\n{\n \"dependencies\": {\n \"needed-package\": \"^1.0.0\"\n }\n}\n```\n\nOr bundle it:\n\n```ts\nexport default defineConfig({\n deps: {\n alwaysBundle: ['needed-package'],\n },\n})\n```\n\n### Type Resolution Errors\n\nUse TypeScript resolver for complex types:\n\n```ts\nexport default defineConfig({\n dts: {\n resolver: 'tsc',\n },\n})\n```\n\n## Summary\n\n**Default behavior:**\n- `dependencies`, `peerDependencies`, & `optionalDependencies` → External\n- `devDependencies` & phantom deps → Bundled if imported\n\n**Override (under `deps`):**\n- `neverBundle` → Force external\n- `alwaysBundle` → Force bundled\n- `onlyBundle` → Whitelist bundled deps\n- `onlyImport` → Whitelist runtime imports in output\n- `neverBundle: true` → Externalize all dependencies\n- `resolveDepSubpath: true` → Resolve external dependency subpath imports to package-relative paths\n\n**Declaration files:**\n- Same bundling logic as JavaScript\n- Use `resolver: 'tsc'` for complex types\n\n## Tips\n\n1. **Keep dependencies external** for libraries\n2. **Bundle everything** for standalone CLIs\n3. **Use regex patterns** for namespaced packages\n4. **Check bundle size** to verify external/bundled split\n5. **Test with fresh install** to catch missing dependencies\n6. **Use tsc resolver** only when needed (slower)\n\n## Related Options\n\n- [External](option-dependencies.md) - This page\n- [Platform](option-platform.md) - Runtime environment\n- [Output Format](option-output-format.md) - Module formats\n- [DTS](option-dts.md) - Type declarations\n",".agents/skills/tsdown/references/option-dts.md":"# TypeScript Declaration Files\n\nGenerate `.d.ts` type declaration files for your library.\n\n## Overview\n\ntsdown uses [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts) to generate and bundle TypeScript declaration files.\n\n**Requirements:**\n- TypeScript must be installed in your project\n\n## Enabling DTS Generation\n\n### Auto-Enabled\n\nDTS generation is **automatically enabled** if `package.json` contains:\n- `types` field, or\n- `typings` field\n\n### Manual Enable\n\n#### CLI\n\n```bash\ntsdown --dts\n```\n\n#### Config File\n\n```ts\nexport default defineConfig({\n dts: true,\n})\n```\n\n## Performance\n\n### With `isolatedDeclarations` (Recommended)\n\n**Extremely fast** - uses oxc-transform for generation.\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"isolatedDeclarations\": true\n }\n}\n```\n\n### Without `isolatedDeclarations`\n\nFalls back to TypeScript compiler. Reliable but slower.\n\n## Declaration Maps\n\nMap `.d.ts` files back to original `.ts` sources (useful for monorepos).\n\n### Enable in tsconfig.json\n\n```json\n{\n \"compilerOptions\": {\n \"declarationMap\": true\n }\n}\n```\n\n### Enable in tsdown Config\n\n```ts\nexport default defineConfig({\n dts: {\n sourcemap: true,\n },\n})\n```\n\n## Advanced Options\n\n### Custom Compiler Options\n\nOverride TypeScript compiler options:\n\n```ts\nexport default defineConfig({\n dts: {\n compilerOptions: {\n removeComments: false,\n },\n },\n})\n```\n\n## Build Process\n\n- **ESM format**: `.js` and `.d.ts` files generated in same build\n- **CJS format**: Separate build process for `.d.ts` files\n\n## Common Patterns\n\n### Basic Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nOutput:\n- `dist/index.mjs`\n- `dist/index.cjs`\n- `dist/index.d.ts`\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nOutput:\n- `dist/index.mjs`, `dist/index.cjs`, `dist/index.d.ts`\n- `dist/utils.mjs`, `dist/utils.cjs`, `dist/utils.d.ts`\n\n### With Monorepo Support\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: {\n sourcemap: true, // Enable declaration maps\n },\n})\n```\n\n### Fast Build (Isolated Declarations)\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"isolatedDeclarations\": true,\n \"declaration\": true,\n \"declarationMap\": true\n }\n}\n```\n\n```ts\n// tsdown.config.ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true, // Will use fast oxc-transform\n})\n```\n\n## Troubleshooting\n\n### Missing Types\n\nEnsure TypeScript is installed:\n\n```bash\npnpm add -D typescript\n```\n\n### Slow Generation\n\nEnable `isolatedDeclarations` in `tsconfig.json` for faster builds.\n\n### Declaration Errors\n\nCheck that all exports have explicit types (required for `isolatedDeclarations`).\n\n### Report Issues\n\nFor DTS-specific issues, report to [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts/issues).\n\n### Vue Support\n\nEnable Vue component type generation (requires `vue-tsc`):\n\n```ts\nexport default defineConfig({\n dts: {\n vue: true,\n },\n})\n```\n\n### Oxc Transform\n\nControl Oxc usage for declaration generation:\n\n```ts\nexport default defineConfig({\n dts: {\n oxc: true, // Use oxc-transform (fast, requires isolatedDeclarations)\n },\n})\n```\n\n### Custom TSConfig\n\nSpecify a different tsconfig for DTS generation:\n\n```ts\nexport default defineConfig({\n dts: {\n tsconfig: './tsconfig.build.json',\n },\n})\n```\n\n## Available DTS Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `sourcemap` | `boolean` | Generate declaration source maps |\n| `compilerOptions` | `object` | Override TypeScript compiler options |\n| `vue` | `boolean` | Enable Vue type generation (requires vue-tsc) |\n| `oxc` | `boolean` | Use oxc-transform for fast generation |\n| `tsconfig` | `string` | Path to tsconfig file |\n| `resolver` | `'oxc' \\| 'tsc'` | Module resolver: `'oxc'` (default, fast) or `'tsc'` (more compatible) |\n| `cjsDefault` | `boolean` | CJS default export handling |\n| `sideEffects` | `boolean` | Preserve side effects in declarations |\n\n## Tips\n\n1. **Always enable DTS** for TypeScript libraries\n2. **Use isolatedDeclarations** for fast builds\n3. **Enable declaration maps** in monorepos\n4. **Ensure explicit types** for all exports\n5. **Install TypeScript** as dev dependency\n\n## Related Options\n\n- [Entry](option-entry.md) - Configure entry points\n- [Output Format](option-output-format.md) - Multiple output formats\n- [Target](option-target.md) - JavaScript version\n",".agents/skills/tsdown/references/option-entry.md":"# Entry Points\n\nConfigure which files to bundle as entry points.\n\n## Overview\n\nEntry points are the starting files for the bundling process. Each entry point generates a separate bundle.\n\n## Usage Patterns\n\n### CLI\n\n```bash\n# Single entry\ntsdown src/index.ts\n\n# Multiple entries\ntsdown src/index.ts src/cli.ts\n\n# Glob patterns\ntsdown 'src/*.ts'\n```\n\n### Config File\n\n#### Single Entry\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n})\n```\n\n#### Multiple Entries (Array)\n\n```ts\nexport default defineConfig({\n entry: ['src/entry1.ts', 'src/entry2.ts'],\n})\n```\n\n#### Named Entries (Object)\n\n```ts\nexport default defineConfig({\n entry: {\n main: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n})\n```\n\nOutput files will match the keys:\n- `dist/main.mjs`\n- `dist/utils.mjs`\n- `dist/cli.mjs`\n\n## Glob Patterns\n\nMatch multiple files dynamically using glob patterns:\n\n### All TypeScript Files\n\n```ts\nexport default defineConfig({\n entry: 'src/**/*.ts',\n})\n```\n\n### Exclude Test Files\n\n```ts\nexport default defineConfig({\n entry: ['src/*.ts', '!src/*.test.ts'],\n})\n```\n\n### Object Entries with Glob Patterns\n\nUse glob wildcards (`*`) in both keys and values. The `*` in the key acts as a placeholder replaced with the matched file name (without extension):\n\n```ts\nexport default defineConfig({\n entry: {\n // Maps src/foo.ts → dist/lib/foo.js, src/bar.ts → dist/lib/bar.js\n 'lib/*': 'src/*.ts',\n },\n})\n```\n\n#### Negation Patterns in Object Entries\n\nValues can be an array with negation patterns (`!`):\n\n```ts\nexport default defineConfig({\n entry: {\n 'hooks/*': ['src/hooks/*.ts', '!src/hooks/index.ts'],\n },\n})\n```\n\nMultiple positive and negation patterns:\n\n```ts\nexport default defineConfig({\n entry: {\n 'utils/*': [\n 'src/utils/*.ts',\n 'src/utils/*.tsx',\n '!src/utils/index.ts',\n '!src/utils/internal.ts',\n ],\n },\n})\n```\n\n**Warning:** Multiple positive patterns in an array value must share the same base directory.\n\n### Mixed Entries\n\nMix strings, glob patterns, and object entries in an array:\n\n```ts\nexport default defineConfig({\n entry: [\n 'src/*',\n '!src/foo.ts',\n { main: 'index.ts' },\n { 'lib/*': ['src/*.ts', '!src/bar.ts'] },\n ],\n})\n```\n\nObject entries take precedence when output names conflict.\n\n### Windows Compatibility\n\nUse forward slashes `/` instead of backslashes `\\` on Windows:\n\n```ts\n// ✅ Correct\nentry: 'src/utils/*.ts'\n\n// ❌ Wrong on Windows\nentry: 'src\\\\utils\\\\*.ts'\n```\n\n## Common Patterns\n\n### Library with Main Export\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### Library with Multiple Exports\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n client: 'src/client.ts',\n server: 'src/server.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### CLI Tool\n\n```ts\nexport default defineConfig({\n entry: {\n cli: 'src/cli.ts',\n },\n format: ['esm'],\n platform: 'node',\n})\n```\n\n### Preserve Directory Structure\n\nUse with `unbundle: true` to keep file structure:\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n unbundle: true,\n format: ['esm'],\n dts: true,\n})\n```\n\nThis will output files matching the source structure:\n- `src/index.ts` → `dist/index.mjs`\n- `src/utils/helper.ts` → `dist/utils/helper.mjs`\n\n## Tips\n\n1. **Use glob patterns** for multiple related files\n2. **Use object syntax** for custom output names\n3. **Exclude test files** with negation patterns `!**/*.test.ts`\n4. **Combine with unbundle** to preserve directory structure\n5. **Use named entries** for better control over output filenames\n",".agents/skills/tsdown/references/option-exe.md":"# Executable - `exe`\n\n**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html).\n\n## Requirements\n\n- Node.js >= 25.7.0\n- Not supported in Bun or Deno\n\n## Basic Usage\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: true,\n})\n```\n\n## Behavior When Enabled\n\n- Declaration file generation (`dts`) is disabled by default\n- Code splitting is disabled\n- Only single entry points are supported\n- Legacy CJS warnings are suppressed\n\n## Advanced Configuration\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n fileName: 'my-tool',\n seaConfig: {\n disableExperimentalSEAWarning: true,\n useCodeCache: true,\n useSnapshot: false,\n },\n },\n})\n```\n\n## `ExeOptions`\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `seaConfig` | `Omit` | Node.js configuration options |\n| `fileName` | `string \\| ((chunk) => string)` | Custom output file name (without `.exe` or platform suffixes) |\n| `targets` | `ExeTarget[]` | Cross-platform build targets (requires `@tsdown/exe`) |\n\n## `SeaConfig`\n\nSee [Node.js Single Executable Applications documentation](https://nodejs.org/api/single-executable-applications.html).\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `disableExperimentalSEAWarning` | `boolean` | `true` | Disable the experimental warning |\n| `useSnapshot` | `boolean` | `false` | Use V8 snapshot |\n| `useCodeCache` | `boolean` | `false` | Use V8 code cache |\n| `execArgv` | `string[]` | - | Extra Node.js arguments |\n| `execArgvExtension` | `'none' \\| 'env' \\| 'cli'` | `'env'` | How to extend execArgv |\n| `assets` | `Record` | - | Assets to embed |\n\n## Cross-Platform Builds\n\nInstall `@tsdown/exe` to build executables for multiple platforms from a single machine:\n\n```bash\npnpm add -D @tsdown/exe\n```\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [\n { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },\n { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },\n { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },\n ],\n },\n})\n```\n\nThis downloads the target platform's Node.js binary, caches it locally, and produces platform-suffixed output:\n\n```\ndist/\n cli-linux-x64\n cli-darwin-arm64\n cli-win-x64.exe\n```\n\n### `ExeTarget`\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `platform` | `'win' \\| 'darwin' \\| 'linux'` | Target OS (nodejs.org naming) |\n| `arch` | `'x64' \\| 'arm64'` | Target CPU architecture |\n| `nodeVersion` | `string` | Node.js version (must be `>=25.7.0`), or `'latest'` / `'latest-lts'` to resolve automatically |\n\n### Custom Node.js Index and Download URL\n\nWhen downloading Node.js binaries (e.g. behind a corporate proxy or using a mirror), you can customize the sources:\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [{ platform: 'linux', arch: 'x64', nodeVersion: 'latest-lts' }],\n // Index used to resolve 'latest' / 'latest-lts' versions\n nodeDistIndexUrl: 'https://mirrors.example.com/node/index.json', // default: https://nodejs.org/dist/index.json\n // Fully custom download URL per target\n getDownloadUrl: (target) =>\n `https://mirrors.example.com/node/v${target.nodeVersion}/node-v${target.nodeVersion}-${target.platform}-${target.arch}.tar.gz`,\n },\n})\n```\n\n### Caching\n\nDownloaded Node.js binaries are cached in system cache directories:\n- **macOS:** `~/Library/Caches/tsdown/node/`\n- **Linux:** `~/.cache/tsdown/node/`\n- **Windows:** `%LOCALAPPDATA%/tsdown/Caches/node/`\n\n## Platform Notes\n\n- On macOS, the executable is automatically codesigned (ad-hoc) for Gatekeeper compatibility\n- On Windows, the `.exe` extension is automatically appended\n- When `targets` is specified, `seaConfig.executable` is ignored\n\n## CLI\n\n```bash\ntsdown --exe\ntsdown src/cli.ts --exe\n```\n",".agents/skills/tsdown/references/option-lint.md":"# Package Validation (publint & attw)\n\nValidate your package configuration and type declarations before publishing.\n\n## Overview\n\ntsdown integrates with [publint](https://publint.dev/) and [Are the types wrong?](https://arethetypeswrong.github.io/) (attw) to catch common packaging issues. Both are optional dependencies.\n\n## Installation\n\n```bash\n# publint only\nnpm install -D publint\n\n# attw only\nnpm install -D @arethetypeswrong/core\n\n# both\nnpm install -D publint @arethetypeswrong/core\n```\n\n## publint\n\nChecks that `package.json` fields (`exports`, `main`, `module`, `types`) match your actual output files.\n\n### Enable\n\n```ts\nexport default defineConfig({\n publint: true,\n})\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n publint: {\n level: 'error', // 'warning' | 'error' | 'suggestion'\n },\n})\n```\n\n### CLI\n\n```bash\ntsdown --publint\n```\n\n## attw (Are the types wrong?)\n\nVerifies TypeScript declarations are correct across different module resolution strategies (`node10`, `node16`, `bundler`).\n\n### Enable\n\n```ts\nexport default defineConfig({\n attw: true,\n})\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n attw: {\n profile: 'node16', // 'strict' | 'node16' | 'esm-only'\n level: 'error', // 'warn' | 'error'\n ignoreRules: ['false-cjs', 'cjs-resolves-to-esm'],\n },\n})\n```\n\n### Profiles\n\n| Profile | Description |\n|---------|-------------|\n| `strict` | Requires all resolutions to pass (default) |\n| `node16` | Ignores `node10` resolution failures |\n| `esm-only` | Ignores `node10` and `node16-cjs` resolution failures |\n\n### Ignore Rules\n\nSuppress specific problem types with `ignoreRules`:\n\n| Rule | Description |\n|------|-------------|\n| `no-resolution` | Module could not be resolved |\n| `untyped-resolution` | Resolution succeeded but has no types |\n| `false-cjs` | Types indicate CJS but implementation is ESM |\n| `false-esm` | Types indicate ESM but implementation is CJS |\n| `cjs-resolves-to-esm` | CJS resolution points to an ESM module |\n| `fallback-condition` | A fallback/wildcard condition was used |\n| `cjs-only-exports-default` | CJS module only exports a default |\n| `named-exports` | Named exports mismatch between types and implementation |\n| `false-export-default` | Types declare a default export that doesn't exist |\n| `missing-export-equals` | Types are missing `export =` for CJS |\n| `unexpected-module-syntax` | File uses unexpected module syntax |\n| `internal-resolution-error` | Internal resolution error in type checking |\n\n### CLI\n\n```bash\ntsdown --attw\n```\n\n## CI Integration\n\nBoth tools support CI-aware options:\n\n```ts\nexport default defineConfig({\n publint: 'ci-only',\n attw: {\n enabled: 'ci-only',\n profile: 'node16',\n level: 'error',\n },\n})\n```\n\nBoth tools require a `package.json` in your project directory.\n\n## Related Options\n\n- [CI Environment](advanced-ci.md) - CI-aware option details\n- [Package Exports](option-package-exports.md) - Generate exports field\n",".agents/skills/tsdown/references/option-log-level.md":"# Log Level\n\nControl the verbosity of build output.\n\n## Overview\n\nThe `logLevel` option controls how much information tsdown displays during the build process.\n\n## Type\n\n```ts\nlogLevel?: 'silent' | 'error' | 'warn' | 'info'\n```\n\n**Default:** `'info'`\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Suppress all output\ntsdown --log-level silent\n\n# Only show errors\ntsdown --log-level error\n\n# Show warnings and errors\ntsdown --log-level warn\n\n# Show all info (default)\ntsdown --log-level info\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'error',\n})\n```\n\n## Available Levels\n\n| Level | Shows | Use Case |\n|-------|-------|----------|\n| `silent` | Nothing | CI/CD pipelines, scripting |\n| `error` | Errors only | Minimal output |\n| `warn` | Warnings + errors | Standard CI/CD |\n| `info` | All messages | Development (default) |\n\n## Common Patterns\n\n### CI/CD Pipeline\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'error', // Only show errors in CI\n})\n```\n\n### Scripting\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'silent', // No output for automation\n})\n```\n\n## Fail on Warnings\n\nThe `failOnWarn` option controls whether warnings cause the build to exit with a non-zero code. Defaults to `false` — warnings never fail the build.\n\n```ts\nexport default defineConfig({\n failOnWarn: false, // Default: never fail on warnings\n // failOnWarn: true, // Always fail on warnings\n // failOnWarn: 'ci-only', // Fail on warnings only in CI\n})\n```\n\nSee [CI Environment](advanced-ci.md) for more about CI-aware options.\n\n## Suppressing Warnings\n\nThe `suppressWarnings` option silences warnings whose message matches a given pattern. This is useful for opting out of non-actionable notices (such as the TypeScript 7.0 experimental API warning) while keeping other warnings visible.\n\n### Type\n\n```ts\nsuppressWarnings?:\n | string\n | RegExp\n | Array\n | ((msg: string) => boolean)\n```\n\n- **string** – substring match\n- **RegExp** – regular expression match\n- **array** – matches if any entry matches\n- **function** – custom predicate\n\n### Usage\n\n```ts\nexport default defineConfig({\n suppressWarnings: [\n 'is experimental', // substring match\n /Circular dependency/, // regexp match\n ],\n // Or a predicate function:\n // suppressWarnings: (msg) => msg.includes('is experimental'),\n})\n```\n\nMatched warnings are dropped **before** `failOnWarn` is applied, so a suppressed warning will not fail the build even when `failOnWarn: true`.\n\n## Related Options\n\n- [CI Environment](advanced-ci.md) - CI-aware option details\n- [CLI Reference](reference-cli.md) - All CLI options\n- [Config File](option-config-file.md) - Configuration setup\n",".agents/skills/tsdown/references/option-minification.md":"# Minification\n\nCompress code to reduce bundle size.\n\n## Overview\n\nMinification removes unnecessary characters (whitespace, comments) and optimizes code for production, reducing bundle size and improving load times.\n\n**Note:** Uses [Oxc minifier](https://oxc.rs/docs/contribute/minifier) internally. The minifier is currently in alpha.\n\n## Type\n\n```ts\nminify?: boolean | 'dce-only' | MinifyOptions\n```\n\n- `true` — Enable full minification (whitespace removal, mangling, compression)\n- `false` — Disable minification (default)\n- `'dce-only'` — Only perform dead code elimination without full minification\n- `MinifyOptions` — Pass detailed options to the Oxc minifier\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Enable minification\ntsdown --minify\n\n# Disable minification\ntsdown --no-minify\n```\n\n**Note:** The CLI `--minify` flag is a boolean toggle. For `'dce-only'` mode or advanced options, use the config file.\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n minify: true,\n})\n```\n\n### DCE-Only Mode\n\nRemove dead code without full minification (keeps readable output):\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n minify: 'dce-only',\n})\n```\n\n## Example Output\n\n### Without Minification\n\n```js\n// dist/index.mjs\nconst x = 1\n\nfunction hello(x$1) {\n console.log('Hello World')\n console.log(x$1)\n}\n\nhello(x)\n```\n\n### With Minification\n\n```js\n// dist/index.mjs\nconst e=1;function t(e){console.log(`Hello World`),console.log(e)}t(e);\n```\n\n## Common Patterns\n\n### Production Build\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: true,\n clean: true,\n})\n```\n\n### Conditional Minification\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: !options.watch, // Only minify in production\n}))\n```\n\n### Browser Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n minify: true,\n})\n```\n\n### Multiple Builds\n\n```ts\nexport default defineConfig([\n // Development build\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: false,\n outDir: 'dist/dev',\n },\n // Production build\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: true,\n outDir: 'dist/prod',\n },\n])\n```\n\n## CLI Examples\n\n```bash\n# Production build with minification\ntsdown --minify --clean\n\n# Multiple formats with minification\ntsdown --format esm --format cjs --minify\n\n# Conditional minification (only when not watching)\ntsdown --minify # Or omit --watch\n```\n\n## Tips\n\n1. **Use `minify: true`** for production builds\n2. **Use `'dce-only'`** to remove dead code while keeping output readable\n3. **Skip minification** during development for faster rebuilds\n4. **Combine with tree shaking** for best results\n5. **Test minified output** thoroughly (Oxc minifier is in alpha)\n\n## Troubleshooting\n\n### Minified Code Has Bugs\n\nOxc minifier is in alpha and may have issues:\n\n1. **Use DCE-only mode**: `minify: 'dce-only'`\n2. **Report bug** to [Oxc project](https://github.com/oxc-project/oxc/issues)\n3. **Disable minification**: `minify: false`\n\n### Unexpected Output\n\n- **Test unminified** first to isolate issue\n- **Check source maps** for debugging\n- **Verify target compatibility**\n\n## Related Options\n\n- [Tree Shaking](option-tree-shaking.md) - Remove unused code\n- [Target](option-target.md) - Syntax transformations\n- [Output Format](option-output-format.md) - Module formats\n- [Sourcemap](option-sourcemap.md) - Debug information\n",".agents/skills/tsdown/references/option-output-directory.md":"# Output Directory\n\nConfigure the output directory for bundled files.\n\n## Overview\n\nBy default, tsdown outputs bundled files to the `dist` directory. You can customize this location using the `outDir` option.\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Default output to dist/\ntsdown\n\n# Custom output directory\ntsdown --out-dir build\ntsdown -d lib\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: 'build',\n})\n```\n\n## Common Patterns\n\n### Standard Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist', // Default\n dts: true,\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n├── index.cjs\n└── index.d.ts\n```\n\n### Separate Directories by Format\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n outDir: 'dist/esm',\n },\n {\n entry: ['src/index.ts'],\n format: ['cjs'],\n outDir: 'dist/cjs',\n },\n])\n```\n\n**Output:**\n```\ndist/\n├── esm/\n│ └── index.js\n└── cjs/\n └── index.js\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: 'lib', // Custom directory\n clean: true,\n})\n```\n\n### Build to Root\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: '.', // Output to project root (not recommended)\n clean: false, // Don't clean root!\n})\n```\n\n**Warning:** Be careful when outputting to root to avoid deleting important files.\n\n## Output Extensions\n\n### Custom Extensions\n\nUse `outExtensions` to control file extensions:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n outExtensions({ format }) {\n return {\n js: format === 'esm' ? '.mjs' : '.cjs',\n }\n },\n})\n```\n\n### Default Extensions\n\n| Format | Default Extension | With `type: \"module\"` |\n|--------|-------------------|----------------------|\n| `esm` | `.mjs` | `.js` |\n| `cjs` | `.cjs` | `.js` |\n| `iife` | `.iife.js` | `.iife.js` |\n| `umd` | `.umd.js` | `.umd.js` |\n\nFor IIFE/UMD builds, `outExtensions` customizes extensions or suffixes but does not remove the built-in `.iife` or `.umd` segment. Use `outputOptions.entryFileNames` for custom full filename patterns.\n\n### ESM with .js Extension\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm'],\n outExtensions: () => ({ js: '.js' }),\n})\n```\n\nRequires `\"type\": \"module\"` in package.json.\n\n## File Naming\n\n### Entry Names\n\nControl output filenames based on entry names:\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n },\n outDir: 'dist',\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n└── utils.mjs\n```\n\n### Glob Entry\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n outDir: 'dist',\n unbundle: true, // Preserve structure\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n├── utils/\n│ └── helper.mjs\n└── components/\n └── button.mjs\n```\n\n## Multiple Builds\n\n### Same Output Directory\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true, // Clean first\n },\n {\n entry: ['src/cli.ts'],\n outDir: 'dist',\n clean: false, // Don't clean again\n },\n])\n```\n\n### Different Output Directories\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist/lib',\n },\n {\n entry: ['src/cli.ts'],\n format: ['esm'],\n outDir: 'dist/bin',\n },\n])\n```\n\n## CLI Examples\n\n```bash\n# Default\ntsdown\n\n# Custom directory\ntsdown --out-dir build\ntsdown -d lib\n\n# Nested directory\ntsdown --out-dir dist/lib\n\n# With other options\ntsdown --out-dir build --format esm,cjs --dts\n```\n\n## Tips\n\n1. **Use default `dist`** for standard projects\n2. **Be careful with root** - avoid `outDir: '.'`\n3. **Clean before build** - use `clean: true`\n4. **Consistent naming** - match your project conventions\n5. **Separate by format** if needed for clarity\n6. **Check .gitignore** - ensure output dir is ignored\n\n## Troubleshooting\n\n### Files Not in Expected Location\n\n- Check `outDir` config\n- Verify build completed successfully\n- Look for typos in path\n\n### Files Deleted Unexpectedly\n\n- Check if `clean: true`\n- Ensure outDir doesn't overlap with source\n- Don't use root as outDir\n\n### Permission Errors\n\n- Check write permissions\n- Ensure directory isn't locked\n- Try different location\n\n## Related Options\n\n- [Cleaning](option-cleaning.md) - Clean output directory\n- [Entry](option-entry.md) - Entry points\n- [Output Format](option-output-format.md) - Module formats\n- [Unbundle](option-unbundle.md) - Preserve structure\n",".agents/skills/tsdown/references/option-output-format.md":"# Output Format\n\nConfigure the module format(s) for generated bundles.\n\n## Overview\n\ntsdown can generate bundles in multiple formats. Default is ESM.\n\n## Available Formats\n\n| Format | Description | Use Case |\n|--------|-------------|----------|\n| `esm` | ECMAScript Module (default) | Modern Node.js, browsers, Deno |\n| `cjs` | CommonJS | Legacy Node.js, require() |\n| `iife` | Immediately Invoked Function Expression | Browser `\n\n\n\n\n```\n\n### Export Components\n\n```ts\n// src/index.ts\nexport { default as Button } from './Button.vue'\nexport { default as Input } from './Input.vue'\nexport { default as Modal } from './Modal.vue'\n\n// Re-export types\nexport type { ButtonProps } from './Button.vue'\n```\n\n## Common Patterns\n\n### Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n platform: 'neutral',\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [\n Vue({\n isProduction: true,\n style: {\n trim: true,\n },\n }),\n ],\n dts: {\n vue: true,\n },\n clean: true,\n})\n```\n\n### Multiple Components\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n Button: 'src/Button.vue',\n Input: 'src/Input.vue',\n Modal: 'src/Modal.vue',\n },\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [Vue({ isProduction: true })],\n dts: { vue: true },\n})\n```\n\n### With Composition Utilities\n\n```ts\n// src/composables/useCounter.ts\nimport { ref } from 'vue'\n\nexport function useCounter(initial = 0) {\n const count = ref(initial)\n const increment = () => count.value++\n const decrement = () => count.value--\n return { count, increment, decrement }\n}\n```\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [Vue({ isProduction: true })],\n dts: { vue: true },\n})\n```\n\n### TypeScript Configuration\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"ESNext\",\n \"lib\": [\"ES2020\", \"DOM\", \"DOM.Iterable\"],\n \"jsx\": \"preserve\",\n \"moduleResolution\": \"bundler\",\n \"allowImportingTsExtensions\": true,\n \"strict\": true,\n \"isolatedDeclarations\": true,\n \"skipLibCheck\": true\n },\n \"include\": [\"src\"],\n \"exclude\": [\"node_modules\", \"dist\"]\n}\n```\n\n### Package.json Configuration\n\n```json\n{\n \"name\": \"my-vue-library\",\n \"version\": \"1.0.0\",\n \"type\": \"module\",\n \"main\": \"./dist/index.cjs\",\n \"module\": \"./dist/index.mjs\",\n \"types\": \"./dist/index.d.ts\",\n \"exports\": {\n \".\": {\n \"types\": \"./dist/index.d.ts\",\n \"import\": \"./dist/index.mjs\",\n \"require\": \"./dist/index.cjs\"\n },\n },\n \"files\": [\"dist\"],\n \"peerDependencies\": {\n \"vue\": \"^3.0.0\"\n },\n \"devDependencies\": {\n \"tsdown\": \"^0.9.0\",\n \"typescript\": \"^5.0.0\",\n \"unplugin-vue\": \"^5.0.0\",\n \"vue\": \"^3.4.0\",\n \"vue-tsc\": \"^2.0.0\"\n }\n}\n```\n\n## Advanced Patterns\n\n### With Vite Plugins\n\nSome Vite Vue plugins may work:\n\n```ts\nimport Vue from 'unplugin-vue/rolldown'\nimport Components from 'unplugin-vue-components/rolldown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [\n Vue({ isProduction: true }),\n Components({\n dts: 'src/components.d.ts',\n }),\n ],\n dts: { vue: true },\n})\n```\n\n### JSX Support\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [\n Vue({\n isProduction: true,\n script: {\n propsDestructure: true,\n },\n }),\n ],\n inputOptions: {\n transform: {\n jsx: 'automatic',\n jsxImportSource: 'vue',\n },\n },\n dts: { vue: true },\n})\n```\n\n### Monorepo Vue Packages\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue', /^@mycompany\\//],\n },\n plugins: [Vue({ isProduction: true })],\n dts: { vue: true },\n})\n```\n\n## Plugin Options\n\n### unplugin-vue Options\n\n```ts\nVue({\n isProduction: true,\n script: {\n defineModel: true,\n propsDestructure: true,\n },\n style: {\n trim: true,\n },\n template: {\n compilerOptions: {\n isCustomElement: (tag) => tag.startsWith('custom-'),\n },\n },\n})\n```\n\n## Tips\n\n1. **Always externalize Vue** - Don't bundle Vue itself\n2. **Enable vue: true in dts** - For proper type generation\n3. **Use platform: 'neutral'** - Maximum compatibility\n4. **Install vue-tsc** - Required for type generation\n5. **Set isProduction: true** - Optimize for production\n6. **Add peer dependency** - Vue as peer dependency\n\n## Troubleshooting\n\n### Type Generation Fails\n\nEnsure vue-tsc is installed:\n```bash\npnpm add -D vue-tsc\n```\n\nEnable in config:\n```ts\ndts: { vue: true }\n```\n\n### Component Types Missing\n\nCheck TypeScript config:\n```json\n{\n \"compilerOptions\": {\n \"jsx\": \"preserve\",\n \"moduleResolution\": \"bundler\"\n }\n}\n```\n\n### Vue Not Externalized\n\nAdd to deps.neverBundle:\n```ts\ndeps: {\n neverBundle: ['vue'],\n}\n```\n\n### SFC Compilation Errors\n\nCheck unplugin-vue version:\n```bash\npnpm add -D unplugin-vue@latest\n```\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Dependencies](option-dependencies.md) - External packages\n- [DTS](option-dts.md) - Type declarations\n- [React Recipe](recipe-react.md) - React component libraries\n",".agents/skills/tsdown/references/recipe-wasm.md":"# WASM Support\n\nBundle WebAssembly modules in your TypeScript/JavaScript project.\n\n## Overview\n\ntsdown supports WASM through [`rolldown-plugin-wasm`](https://github.com/sxzz/rolldown-plugin-wasm), enabling direct `.wasm` imports with synchronous and asynchronous instantiation.\n\n## Setup\n\n### Install\n\n```bash\npnpm add -D rolldown-plugin-wasm\n```\n\n### Configure\n\n```ts\nimport { wasm } from 'rolldown-plugin-wasm'\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n plugins: [wasm()],\n})\n```\n\n### TypeScript Support\n\nAdd type declarations to `tsconfig.json`:\n\n```jsonc\n{\n \"compilerOptions\": {\n \"types\": [\"rolldown-plugin-wasm/types\"]\n }\n}\n```\n\n## Importing WASM Modules\n\n### Direct Import\n\n```ts\nimport { add } from './add.wasm'\nadd(1, 2)\n```\n\n### Async Init\n\nUse `?init` query for async initialization:\n\n```ts\nimport init from './add.wasm?init'\nconst instance = await init(imports) // imports optional\ninstance.exports.add(1, 2)\n```\n\n### Sync Init\n\nUse `?init&sync` query for synchronous initialization:\n\n```ts\nimport initSync from './add.wasm?init&sync'\nconst instance = initSync(imports) // imports optional\ninstance.exports.add(1, 2)\n```\n\n## wasm-bindgen Support\n\n### Target `bundler` (Recommended)\n\n```ts\nimport { add } from 'some-pkg'\nadd(1, 2)\n```\n\n### Target `web` (Node.js)\n\n```ts\nimport { readFile } from 'node:fs/promises'\nimport init, { add } from 'some-pkg'\nimport wasmUrl from 'some-pkg/add_bg.wasm?url'\n\nawait init({\n module_or_path: readFile(new URL(wasmUrl, import.meta.url)),\n})\nadd(1, 2)\n```\n\n### Target `web` (Browser)\n\n```ts\nimport init, { add } from 'some-pkg/add.js'\nimport wasmUrl from 'some-pkg/add_bg.wasm?url'\n\nawait init({ module_or_path: wasmUrl })\nadd(1, 2)\n```\n\n`nodejs` and `no-modules` wasm-bindgen targets are not supported.\n\n## Plugin Options\n\n```ts\nwasm({\n maxFileSize: 14 * 1024, // Max size for inline (default: 14KB)\n fileName: '[hash][extname]', // Output file name pattern\n targetEnv: 'auto', // 'auto' | 'auto-inline' | 'browser' | 'node'\n})\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `maxFileSize` | `14 * 1024` | Max file size for inlining. Set to `0` to always copy. |\n| `fileName` | `'[hash][extname]'` | Pattern for emitted WASM files |\n| `targetEnv` | `'auto'` | `'auto'` detects at runtime; `'browser'` omits Node builtins; `'node'` omits fetch |\n\n## Related Options\n\n- [Plugins](advanced-plugins.md) - Plugin system overview\n- [Platform](option-platform.md) - Target platform configuration\n",".agents/skills/tsdown/references/reference-cli.md":"# CLI Reference\n\nComplete reference for tsdown command-line interface.\n\n## Overview\n\nAll CLI flags can also be set in the config file. CLI flags override config file options.\n\n## Flag Patterns\n\nCLI flag mapping rules:\n- `--foo` sets `foo: true`\n- `--no-foo` sets `foo: false`\n- `--foo.bar` sets `foo: { bar: true }`\n- `--format esm --format cjs` sets `format: ['esm', 'cjs']`\n\nCLI flags support both camelCase and kebab-case. For example, `--outDir` and `--out-dir` are equivalent.\n\n## Basic Commands\n\n### Build\n\n```bash\n# Build with default config\ntsdown\n\n# Build specific files\ntsdown src/index.ts src/cli.ts\n\n# Build with watch mode\ntsdown --watch\n```\n\n## Configuration\n\n### `--config, -c `\n\nSpecify custom config file:\n\n```bash\ntsdown --config build.config.ts\ntsdown -c custom-config.js\n```\n\n### `--no-config`\n\nDisable config file loading:\n\n```bash\ntsdown --no-config src/index.ts\n```\n\n### `--config-loader `\n\nChoose config loader (`auto`, `native`, `tsx`, `unrun`). `tsx` and `unrun` are optional peer dependencies — install them manually first:\n\n```bash\ntsdown --config-loader tsx\ntsdown --config-loader unrun\n```\n\n### `--tsconfig `\n\nSpecify TypeScript config file:\n\n```bash\ntsdown --tsconfig tsconfig.build.json\n```\n\n## Entry Points\n\n### `[...files]`\n\nSpecify entry files as arguments:\n\n```bash\ntsdown src/index.ts src/utils.ts\n```\n\n## Output Options\n\n### `--format `\n\nOutput format (`esm`, `cjs`, `iife`, `umd`):\n\n```bash\ntsdown --format esm\ntsdown --format esm --format cjs\n```\n\n### `--out-dir, -d `\n\nOutput directory:\n\n```bash\ntsdown --out-dir lib\ntsdown -d dist\n```\n\n### `--dts`\n\nGenerate TypeScript declarations:\n\n```bash\ntsdown --dts\n```\n\n### `--clean`\n\nClean output directory before build:\n\n```bash\ntsdown --clean\n```\n\n## Build Options\n\n### `--target `\n\nJavaScript target version:\n\n```bash\ntsdown --target es2020\ntsdown --target node18\ntsdown --target chrome100\ntsdown --no-target # Disable transformations\n```\n\n### `--platform `\n\nTarget platform (`node`, `browser`, `neutral`):\n\n```bash\ntsdown --platform node\ntsdown --platform browser\n```\n\n### `--minify`\n\nEnable minification:\n\n```bash\ntsdown --minify\ntsdown --no-minify\n```\n\n### `--sourcemap`\n\nGenerate source maps:\n\n```bash\ntsdown --sourcemap\ntsdown --sourcemap inline\n```\n\n### `--treeshake`\n\nEnable/disable tree shaking:\n\n```bash\ntsdown --treeshake\ntsdown --no-treeshake\n```\n\n## Dependencies\n\n### `--deps.never-bundle `\n\nMark module as external (not bundled):\n\n```bash\ntsdown --deps.never-bundle react --deps.never-bundle react-dom\n```\n\n### `--shims`\n\nAdd ESM/CJS compatibility shims:\n\n```bash\ntsdown --shims\n```\n\n## Development\n\n### `--watch, -w [path]`\n\nEnable watch mode:\n\n```bash\ntsdown --watch\ntsdown -w\ntsdown --watch src # Watch specific directory\n```\n\n### `--ignore-watch `\n\nIgnore paths in watch mode:\n\n```bash\ntsdown --watch --ignore-watch test\n```\n\n### `--on-success `\n\nRun command after successful build:\n\n```bash\ntsdown --watch --on-success \"echo Build complete!\"\n```\n\n## Environment Variables\n\n### `--env.* `\n\nSet compile-time environment variables:\n\n```bash\ntsdown --env.NODE_ENV=production --env.API_URL=https://api.example.com\n```\n\nAccess as `import.meta.env.*` or `process.env.*`.\n\n### `--env-file `\n\nLoad environment variables from file:\n\n```bash\ntsdown --env-file .env.production\n```\n\n### `--env-prefix `\n\nFilter environment variables by prefix (default: `TSDOWN_`):\n\n```bash\ntsdown --env-file .env --env-prefix APP_ --env-prefix TSDOWN_\n```\n\n## Assets\n\n### `--copy `\n\nCopy directory to output:\n\n```bash\ntsdown --copy public\ntsdown --copy assets --copy static\n```\n\n## Executable\n\n### `--exe`\n\n**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html). Requires Node.js >= 25.7.0, not supported in Bun or Deno. Cross-platform builds supported via `@tsdown/exe`.\n\n```bash\ntsdown --exe\n```\n\nWhen enabled:\n- Declaration file generation (`dts`) is disabled by default\n- Code splitting is disabled\n- Only single entry points are supported\n\nSee [Executable](option-exe.md) for advanced configuration and cross-platform builds.\n\n## Package Management\n\n### `--exports`\n\nGenerate the `exports` field in package.json:\n\n```bash\ntsdown --exports\n```\n\n### `--publint`\n\nEnable package validation:\n\n```bash\ntsdown --publint\n```\n\n### `--attw`\n\nEnable \"Are the types wrong\" validation:\n\n```bash\ntsdown --attw\n```\n\n### `--unused`\n\nCheck for unused dependencies:\n\n```bash\ntsdown --unused\n```\n\n## Logging\n\n### `--log-level `\n\nSet logging verbosity (`silent`, `error`, `warn`, `info`):\n\n```bash\ntsdown --log-level error\ntsdown --log-level warn\n```\n\n### `--report` / `--no-report`\n\nEnable/disable build report:\n\n```bash\ntsdown --no-report # Disable size report\ntsdown --report # Enable (default)\n```\n\n### `--debug [feat]`\n\nShow debug logs:\n\n```bash\ntsdown --debug\ntsdown --debug rolldown # Debug specific feature\n```\n\n## Integration\n\n### `--from-vite [vitest]`\n\nExtend Vite or Vitest config:\n\n```bash\ntsdown --from-vite # Use vite.config.*\ntsdown --from-vite vitest # Use vitest.config.*\n```\n\n## Workspace / Monorepo\n\n### `--workspace, -W [dir]`\n\nEnable workspace mode for building multiple packages:\n\n```bash\ntsdown -W\ntsdown -W packages/\n```\n\n### `--filter, -F `\n\nFilter configs by name or working directory. Supports regex:\n\n```bash\ntsdown -W -F my-package\ntsdown -W -F /^pkg-/\n```\n\n### `--concurrency `\n\nMaximum number of Rolldown builds to run in parallel. Defaults to unlimited:\n\n```bash\ntsdown -W --concurrency 4\n```\n\nNot supported in watch mode (ignored with a warning).\n\n### `--unbundle`\n\nEnable unbundle (bundleless) mode:\n\n```bash\ntsdown --unbundle\n```\n\n### `--root `\n\nSpecify the root directory of input files (similar to TypeScript's `rootDir`). Controls the output directory structure by determining how entry file paths map to output paths. Defaults to the common base directory of all entry files.\n\n```bash\ntsdown --root src\ntsdown --root .\n```\n\n### `--fail-on-warn`\n\nFail on warnings (enabled by default):\n\n```bash\ntsdown --no-fail-on-warn # Disable\n```\n\n## Common Usage Patterns\n\n### Basic Build\n\n```bash\ntsdown\n```\n\n### Library (ESM + CJS + Types)\n\n```bash\ntsdown --format esm --format cjs --dts --clean\n```\n\n### Production Build\n\n```bash\ntsdown --minify --clean --no-report\n```\n\n### Development (Watch)\n\n```bash\ntsdown --watch --sourcemap\n```\n\n### Browser Bundle (IIFE)\n\n```bash\ntsdown --format iife --platform browser --minify\n```\n\n### Node.js CLI Tool\n\n```bash\ntsdown --format esm --platform node --shims\n```\n\n### Standalone Executable\n\n```bash\ntsdown src/cli.ts --exe\n```\n\n### Monorepo Package\n\n```bash\ntsdown --clean --dts --exports --publint\n```\n\n### With Environment Variables\n\n```bash\ntsdown --env-file .env.production --env.BUILD_TIME=$(date +%s)\n```\n\n### Copy Assets\n\n```bash\ntsdown --copy public --copy assets --clean\n```\n\n## Tips\n\n1. **Use config file** for complex setups\n2. **CLI flags override** config file options\n3. **Chain multiple formats** for multi-target builds\n4. **Use --clean** to avoid stale files\n5. **Enable --dts** for TypeScript libraries\n6. **Use --watch** during development\n7. **Add --on-success** for post-build tasks\n8. **Use --exports** to auto-generate package.json fields\n\n## Related Documentation\n\n- [Config File](option-config-file.md) - Configuration file options\n- [Entry](option-entry.md) - Entry point configuration\n- [Output Format](option-output-format.md) - Format options\n- [Watch Mode](option-watch-mode.md) - Watch mode details\n","packages/rollup-plugin/README.md":"# [rollup-plugin-chrome-extension](https://www.extend-chrome.dev/rollup-plugin)\n\n[![npm (scoped)](https://img.shields.io/npm/v/rollup-plugin-chrome-extension.svg)](https://www.npmjs.com/package/rollup-plugin-chrome-extension)\n[![GitHub last commit](https://img.shields.io/github/last-commit/crxjs/rollup-plugin-chrome-extension.svg?logo=github)](https://github.com/crxjs/rollup-plugin-chrome-extension)\n![GitHub action badge](https://github.com/crxjs/rollup-plugin-chrome-extension/actions/workflows/rollup-plugin.yml/badge.svg)\n[![TypeScript Declarations Included](https://img.shields.io/badge/types-TypeScript-informational)](#typescript)\n\n\n \"rollup-plugin-chrome-extension\n\nThe bundler configuration for a Chrome Extension can be pretty complex.\n\nUse `manifest.json` as the input. Every file in the manifest will be bundled or\ncopied to the output folder.\n\nRPCE simplifies project config and supports many of Vite's features in the\nChrome Extension environment, including HMR.\n\n## [Documentation](https://www.extend-chrome.dev/rollup-plugin)\n\nWe have\n[v3 boilerplates](https://www.extend-chrome.dev/rollup-plugin#chrome-extension-boilerplates)\nfor [React JavaScript](https://github.com/crxjs/js-react-boilerplate),\n[React TypeScript](https://github.com/crxjs/ts-react-boilerplate) and\n[Svelte](https://github.com/kyrelldixon/svelte-tailwind-extension-boilerplate),\nas well as [instructions](https://www.extend-chrome.dev/rollup-plugin#usage) for\nsetting up your own project.\n\nSee the [documentation](https://www.extend-chrome.dev/rollup-plugin) for usage\nand how to get started.\n\n## Supporting\n\nIf these plugins have helped you ship your product faster, please consider\n[sponsoring me](https://github.com/sponsors/jacksteamdev) on GitHub.\n\n## Contributing\n\nWe encourage pull requests! This is a\n[pnpm monorepo](https://pnpm.io/workspaces), so use pnpm instead of Yarn or npm.\n","packages/vite-plugin/README.md":"![CRXJS](./banner-github.png)\n\n

CRXJS

\n\n

\nModern Chrome extension development with built-in HMR and zero-config setup\n

\n\n

\n\n\"NPM\n\n

\n\n

\n📚 Documentation |\n💬 Discord \n

\n\n\n## 📦 Create CRXJS Project\n```shell\nnpm create crxjs@latest\n``` \n\n> [!IMPORTANT]\n> `@latest` MUST NOT be omitted, otherwise `npm` may resolve to a cached and outdated version of the package.\n\n## ✨ Features\n\n- 🧩 **Full Vite Plugin Ecosystem** - Leverage any Vite-compatible plugins with zero extra setup \n- ⚙️ **Zero Configuration** - Start developing immediately with intelligent defaults \n- 3️⃣ **Manifest V3 Support** - Built for modern Chrome extensions with enhanced security \n- 🔥 **True Hot Module Replacement** - Instant UI updates while preserving extension state 🎈**works with content scripts**\n- 📁 **Static Asset Import** - Directly reference images/fonts in your code\n- 🤖 **Auto Web-Accessible Resources** - Automatic generation of `web_accessible_resources` manifest entries \n\n> [!NOTE] \n> Looking for MV2 support? See [`rollup-plugin`](packages/rollup-plugin/README.md) \n\n## 💻 Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for local development workflows.\n\n## 💝 Contributors\n\nThis project exists thanks to all the people who contribute.\n\nAnd thank you to all our backers! 🙏\n\n\n \n\n\n## 🤝 Supporting\n\nIf these plugins have helped you ship your product faster, please consider\n[sponsoring me](https://github.com/sponsors/jacksteamdev) on GitHub.\n"},"items":[{"name":"README.md","path":".agents/skills/tsdown/README.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/README.md","title":"Tsdown Skill","category":"anthropic-skill","format":"markdown","content":"# tsdown Skills\n\nAgent skills that help AI coding agents understand and work with [tsdown](https://tsdown.dev), the elegant library bundler.\n\n## Installation\n\n```bash\nnpx skills add rolldown/tsdown\n```\n\nThis will install all tsdown skills (including the migration skill). To install only the tsdown skill:\n\n```bash\nnpx skills add rolldown/tsdown --skill tsdown\n```\n\n## What's Included\n\nThe tsdown skill provides Claude Code with knowledge about:\n\n- **Core Concepts** - What tsdown is, why use it, key features\n- **Configuration** - Config file formats, options, multiple configs, workspace support\n- **Build Options** - Entry points, output formats, type declarations, targets\n- **Dependency Handling** - External/inline dependencies, auto-externalization\n- **Output Enhancement** - Shims, CJS defaults, package exports\n- **Framework Support** - React, Vue, Solid, Svelte integration\n- **Advanced Features** - Plugins, hooks, programmatic API, Rolldown options\n- **CLI Commands** - All CLI options and usage patterns\n- **Migration** - Migrating from tsup to tsdown\n\n## Usage\n\nOnce installed, Claude Code will automatically use tsdown knowledge when:\n\n- Building TypeScript/JavaScript libraries\n- Configuring bundlers for library projects\n- Setting up type declaration generation\n- Working with multi-format builds (ESM, CJS, IIFE, UMD)\n- Migrating from tsup\n- Building framework component libraries\n\n### Example Prompts\n\n```\nSet up tsdown to build my TypeScript library with ESM and CJS formats\n```\n\n```\nConfigure tsdown to generate type declarations and bundle for browsers\n```\n\n```\nAdd React support to my tsdown config with Fast Refresh\n```\n\n```\nHelp me migrate from tsup to tsdown\n```\n\n```\nSet up a monorepo build with tsdown workspace support\n```\n\n## Related Skills\n\n- **[tsdown-migrate](https://github.com/rolldown/tsdown/tree/main/skills/tsdown-migrate)** - Dedicated skill for migrating from tsup to tsdown, with complete option mappings, config transformations, and troubleshooting guidance.\n\n## Documentation\n\n- [tsdown Documentation](https://tsdown.dev)\n- [GitHub Repository](https://github.com/rolldown/tsdown)\n- [Rolldown](https://rolldown.rs)\n- [Migration Guide](https://tsdown.dev/guide/migrate-from-tsup)\n\n## License\n\nMIT\n","isInternal":false,"tokens":536,"sizeBytes":2238},{"name":"advanced-benchmark.md","path":".agents/skills/tsdown/references/advanced-benchmark.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/advanced-benchmark.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Benchmark\n\ntsdown delivers exceptional performance:\n\n- **~2x faster** than tsup for standard builds\n- **Up to 8x faster** for TypeScript declaration generation\n\nFor detailed comparisons, see [bundler-benchmark](https://gugustinette.github.io/bundler-benchmark/).\n","isInternal":false,"tokens":62,"sizeBytes":265},{"name":"advanced-ci.md","path":".agents/skills/tsdown/references/advanced-ci.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/advanced-ci.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# CI Environment Support\n\nAutomatically detect CI environments and toggle features based on local vs CI builds.\n\n## Overview\n\ntsdown detects CI from the `CI` environment variable. CI mode is enabled when `process.env.CI` is set to a value other than `0` or `false` (case-insensitive).\n\n## CI-Aware Values\n\nSeveral options accept CI-aware string values:\n\n| Value | Behavior |\n|-------|----------|\n| `true` | Always enabled |\n| `false` | Always disabled |\n| `'ci-only'` | Enabled only in CI, disabled locally |\n| `'local-only'` | Enabled only locally, disabled in CI |\n\n## Supported Options\n\nThese options accept CI-aware values:\n\n- `dts` - TypeScript declaration file generation\n- `publint` - Package lint validation\n- `attw` - \"Are the types wrong\" validation\n- `report` - Bundle size reporting\n- `exports` - Auto-generate `package.json` exports\n- `unused` - Unused dependency check\n- `devtools` - DevTools integration\n- `failOnWarn` - Fail on warnings (defaults to `false`)\n\n## Usage\n\n### String Form\n\n```ts\nexport default defineConfig({\n dts: 'local-only', // Skip DTS in CI for faster builds\n publint: 'ci-only', // Only run publint in CI\n failOnWarn: 'ci-only', // Fail on warnings in CI only (opt-in)\n})\n```\n\n### Object Form\n\nWhen an option takes a configuration object, set `enabled` to a CI-aware value:\n\n```ts\nexport default defineConfig({\n publint: {\n enabled: 'ci-only',\n level: 'error',\n },\n attw: {\n enabled: 'ci-only',\n profile: 'node16',\n },\n})\n```\n\n### Config Function\n\nThe config function receives a `ci` boolean in its context:\n\n```ts\nexport default defineConfig((_, { ci }) => ({\n minify: ci,\n sourcemap: !ci,\n}))\n```\n\n## Typical CI Configuration\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n dts: true,\n failOnWarn: 'ci-only',\n publint: 'ci-only',\n attw: 'ci-only',\n})\n```\n\n## Related Options\n\n- [Package Validation](option-lint.md) - publint and attw configuration\n- [Log Level](option-log-level.md) - `failOnWarn` option details\n","isInternal":false,"tokens":544,"sizeBytes":2034},{"name":"advanced-hooks.md","path":".agents/skills/tsdown/references/advanced-hooks.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/advanced-hooks.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Lifecycle Hooks\n\nExtend the build process with lifecycle hooks.\n\n## Overview\n\nHooks provide a way to inject custom logic at specific stages of the build lifecycle. Inspired by [unbuild](https://github.com/unjs/unbuild).\n\n**Recommendation:** Use [plugins](advanced-plugins.md) for most extensions. Use hooks for simple custom tasks or Rolldown plugin injection.\n\n## Usage Patterns\n\n### Object Syntax\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n hooks: {\n 'build:prepare': async (context) => {\n console.log('Build starting...')\n },\n 'build:done': async (context) => {\n console.log('Build complete!')\n },\n },\n})\n```\n\n### Function Syntax\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n hooks(hooks) {\n hooks.hook('build:prepare', () => {\n console.log('Preparing build...')\n })\n\n hooks.hook('build:before', (context) => {\n console.log(`Building format: ${context.format}`)\n })\n },\n})\n```\n\n## Available Hooks\n\n### `build:prepare`\n\nCalled before the build process starts.\n\n**When:** Once per build session\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Setup tasks\n- Validation\n- Environment preparation\n\n**Example:**\n```ts\nhooks: {\n 'build:prepare': async (context) => {\n console.log('Starting build for:', context.options.entry)\n await cleanOldFiles()\n },\n}\n```\n\n### `build:before`\n\nCalled before each Rolldown build.\n\n**When:** Once per format (ESM, CJS, etc.)\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n buildOptions: BuildOptions,\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Modify build options per format\n- Inject plugins dynamically\n- Format-specific setup\n\n**Example:**\n```ts\nhooks: {\n 'build:before': async (context) => {\n console.log(`Building ${context.buildOptions.format} format...`)\n\n // Add format-specific plugin\n if (context.buildOptions.format === 'iife') {\n context.buildOptions.plugins.push(browserPlugin())\n }\n },\n}\n```\n\n### `build:done`\n\nCalled after the build completes.\n\n**When:** Once per build session\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n chunks: RolldownChunk[],\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Post-processing\n- Asset copying\n- Notifications\n- Deployment\n\n**Example:**\n```ts\nhooks: {\n 'build:done': async (context) => {\n console.log(`Built ${context.chunks.length} chunks`)\n\n // Copy additional files\n await copyAssets()\n\n // Send notification\n notifyBuildComplete()\n },\n}\n```\n\n## Common Patterns\n\n### Build Notifications\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': () => {\n console.log('🚀 Starting build...')\n },\n 'build:done': (context) => {\n const size = context.chunks.reduce((sum, c) => sum + c.code.length, 0)\n console.log(`✅ Build complete! Total size: ${size} bytes`)\n },\n },\n})\n```\n\n### Conditional Plugin Injection\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n hooks.hook('build:before', (context) => {\n // Add minification only for production\n if (process.env.NODE_ENV === 'production') {\n context.buildOptions.plugins.push(minifyPlugin())\n }\n })\n },\n})\n```\n\n### Custom File Copy\n\n```ts\nimport { copyFile } from 'fs/promises'\n\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n // Copy README to dist\n await copyFile('README.md', `${context.options.outDir}/README.md`)\n },\n },\n})\n```\n\n### Build Metrics\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': (context) => {\n context.startTime = Date.now()\n },\n 'build:done': (context) => {\n const duration = Date.now() - context.startTime\n console.log(`Build took ${duration}ms`)\n\n // Log chunk sizes\n context.chunks.forEach((chunk) => {\n console.log(`${chunk.fileName}: ${chunk.code.length} bytes`)\n })\n },\n },\n})\n```\n\n### Format-Specific Logic\n\n```ts\nexport default defineConfig({\n format: ['esm', 'cjs', 'iife'],\n hooks: {\n 'build:before': (context) => {\n const format = context.buildOptions.format\n\n if (format === 'iife') {\n // Browser-specific setup\n context.buildOptions.globalName = 'MyLib'\n } else if (format === 'cjs') {\n // Node-specific setup\n context.buildOptions.platform = 'node'\n }\n },\n },\n})\n```\n\n### Deployment Hook\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n if (process.env.DEPLOY === 'true') {\n console.log('Deploying to CDN...')\n await deployToCDN(context.options.outDir)\n }\n },\n },\n})\n```\n\n## Advanced Usage\n\n### Multiple Hooks\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n // Register multiple hooks\n hooks.hook('build:prepare', setupEnvironment)\n hooks.hook('build:prepare', validateConfig)\n\n hooks.hook('build:before', injectPlugins)\n hooks.hook('build:before', logFormat)\n\n hooks.hook('build:done', generateManifest)\n hooks.hook('build:done', notifyComplete)\n },\n})\n```\n\n### Async Hooks\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': async (context) => {\n await fetchRemoteConfig()\n await initializeDatabase()\n },\n 'build:done': async (context) => {\n await uploadToS3(context.chunks)\n await invalidateCDN()\n },\n },\n})\n```\n\n### Error Handling\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n try {\n await riskyOperation()\n } catch (error) {\n console.error('Hook failed:', error)\n // Don't throw - allow build to complete\n }\n },\n },\n})\n```\n\n## Hookable API\n\ntsdown uses [hookable](https://github.com/unjs/hookable) for hooks. Additional methods:\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n // Register hook\n hooks.hook('build:done', handler)\n\n // Register hook once\n hooks.hookOnce('build:prepare', handler)\n\n // Remove hook\n hooks.removeHook('build:done', handler)\n\n // Clear all hooks for event\n hooks.removeHooks('build:done')\n\n // Call hooks manually\n await hooks.callHook('build:done', context)\n },\n})\n```\n\n## Tips\n\n1. **Use plugins** for most extensions\n2. **Hooks for simple tasks** like notifications or file copying\n3. **Async hooks supported** for I/O operations\n4. **Don't throw errors** unless you want to fail the build\n5. **Context is mutable** in `build:before` for advanced use cases\n6. **Multiple hooks allowed** for the same event\n\n## Troubleshooting\n\n### Hook Not Called\n\n- Verify hook name is correct\n- Check hook is registered in config\n- Ensure async hooks are awaited\n\n### Build Fails in Hook\n\n- Add try/catch for error handling\n- Don't throw unless intentional\n- Log errors for debugging\n\n### Context Undefined\n\n- Check which hook you're using\n- Verify context properties available for that hook\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Rolldown Options](advanced-rolldown-options.md) - Build options\n- [Watch Mode](option-watch-mode.md) - Development workflow\n","isInternal":false,"tokens":1757,"sizeBytes":7051},{"name":"advanced-plugins.md","path":".agents/skills/tsdown/references/advanced-plugins.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/advanced-plugins.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Plugins\n\nExtend tsdown with plugins from multiple ecosystems.\n\n## Overview\n\ntsdown, built on Rolldown, supports plugins from multiple ecosystems to extend and customize the bundling process.\n\n## Supported Ecosystems\n\n### 1. Rolldown Plugins\n\nNative plugins designed for Rolldown:\n\n```ts\nimport RolldownPlugin from 'rolldown-plugin-something'\n\nexport default defineConfig({\n plugins: [RolldownPlugin()],\n})\n```\n\n**Compatibility:** ✅ Full support\n\n### 2. Unplugin\n\nUniversal plugins that work across bundlers:\n\n```ts\nimport UnpluginPlugin from 'unplugin-something'\n\nexport default defineConfig({\n plugins: [UnpluginPlugin.rolldown()],\n})\n```\n\n**Compatibility:** ✅ Most unplugin-* plugins work\n\n**Examples:**\n- `unplugin-vue-components`\n- `unplugin-auto-import`\n- `unplugin-icons`\n\n### 3. Rollup Plugins\n\nMost Rollup plugins work with tsdown:\n\n```ts\nimport RollupPlugin from '@rollup/plugin-something'\n\nexport default defineConfig({\n plugins: [RollupPlugin()],\n})\n```\n\n**Compatibility:** ✅ High compatibility\n\n**Type Issues:** May cause TypeScript errors - use type casting:\n\n```ts\nimport RollupPlugin from 'rollup-plugin-something'\n\nexport default defineConfig({\n plugins: [\n // @ts-expect-error Rollup plugin type mismatch\n RollupPlugin(),\n // Or cast to any\n RollupPlugin() as any,\n ],\n})\n```\n\n### 4. Vite Plugins\n\nSome Vite plugins may work:\n\n```ts\nimport VitePlugin from 'vite-plugin-something'\n\nexport default defineConfig({\n plugins: [\n // @ts-expect-error Vite plugin type mismatch\n VitePlugin(),\n ],\n})\n```\n\n**Compatibility:** ⚠️ Limited - only if not using Vite-specific APIs\n\n**Note:** Improved support planned for future releases.\n\n## Usage\n\n### Basic Plugin Usage\n\n```ts\nimport { defineConfig } from 'tsdown'\nimport SomePlugin from 'some-plugin'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [SomePlugin()],\n})\n```\n\n### Multiple Plugins\n\n```ts\nimport PluginA from 'plugin-a'\nimport PluginB from 'plugin-b'\nimport PluginC from 'plugin-c'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n PluginA(),\n PluginB({ option: true }),\n PluginC(),\n ],\n})\n```\n\n### Conditional Plugins\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n plugins: [\n SomePlugin(),\n options.watch && DevPlugin(),\n !options.watch && ProdPlugin(),\n ].filter(Boolean),\n}))\n```\n\n## Common Plugin Patterns\n\n### JSON Import\n\n```ts\nimport json from '@rollup/plugin-json'\n\nexport default defineConfig({\n plugins: [json()],\n})\n```\n\n### Node Resolve\n\n```ts\nimport { nodeResolve } from '@rollup/plugin-node-resolve'\n\nexport default defineConfig({\n plugins: [nodeResolve()],\n})\n```\n\n### CommonJS\n\n```ts\nimport commonjs from '@rollup/plugin-commonjs'\n\nexport default defineConfig({\n plugins: [commonjs()],\n})\n```\n\n### Replace\n\n```ts\nimport replace from '@rollup/plugin-replace'\n\nexport default defineConfig({\n plugins: [\n replace({\n 'process.env.NODE_ENV': JSON.stringify('production'),\n __VERSION__: JSON.stringify('1.0.0'),\n }),\n ],\n})\n```\n\n### Auto Import\n\n```ts\nimport AutoImport from 'unplugin-auto-import/rolldown'\n\nexport default defineConfig({\n plugins: [\n AutoImport({\n imports: ['vue', 'vue-router'],\n dts: 'src/auto-imports.d.ts',\n }),\n ],\n})\n```\n\n### Vue Components\n\n```ts\nimport Components from 'unplugin-vue-components/rolldown'\n\nexport default defineConfig({\n plugins: [\n Components({\n dts: 'src/components.d.ts',\n }),\n ],\n})\n```\n\n## Framework-Specific Plugins\n\n### React\n\n```ts\nimport react from '@vitejs/plugin-react'\n\nexport default defineConfig({\n entry: ['src/index.tsx'],\n plugins: [\n // @ts-expect-error Vite plugin\n react(),\n ],\n})\n```\n\n### Vue\n\n```ts\nimport vue from '@vitejs/plugin-vue'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n // @ts-expect-error Vite plugin\n vue(),\n ],\n})\n```\n\n### Solid\n\n```ts\nimport solid from 'vite-plugin-solid'\n\nexport default defineConfig({\n entry: ['src/index.tsx'],\n plugins: [\n // @ts-expect-error Vite plugin\n solid(),\n ],\n})\n```\n\n### Svelte\n\n```ts\nimport { svelte } from '@sveltejs/vite-plugin-svelte'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n // @ts-expect-error Vite plugin\n svelte(),\n ],\n})\n```\n\n## Writing Custom Plugins\n\nFollow Rolldown's plugin development guide:\n\n### Basic Plugin Structure\n\n```ts\nimport type { Plugin } from 'rolldown'\n\nfunction myPlugin(): Plugin {\n return {\n name: 'my-plugin',\n\n // Transform hook\n transform(code, id) {\n if (id.endsWith('.custom')) {\n return {\n code: transformCode(code),\n map: null,\n }\n }\n },\n\n // Other hooks...\n }\n}\n```\n\n### Using Custom Plugin\n\n```ts\nimport { myPlugin } from './my-plugin'\n\nexport default defineConfig({\n plugins: [myPlugin()],\n})\n```\n\n## Plugin Configuration\n\n### Plugin-Specific Options\n\nRefer to each plugin's documentation for configuration options.\n\n### Plugin Order\n\nPlugins run in the order they're defined:\n\n```ts\nexport default defineConfig({\n plugins: [\n PluginA(), // Runs first\n PluginB(), // Runs second\n PluginC(), // Runs last\n ],\n})\n```\n\n## Troubleshooting\n\n### Type Errors with Rollup/Vite Plugins\n\nUse type casting:\n\n```ts\nplugins: [\n // Option 1: @ts-expect-error\n // @ts-expect-error Plugin type mismatch\n SomePlugin(),\n\n // Option 2: as any\n SomePlugin() as any,\n]\n```\n\n### Plugin Not Working\n\n1. **Check compatibility** - Verify plugin supports your bundler\n2. **Read documentation** - Follow plugin's setup instructions\n3. **Check plugin order** - Some plugins depend on execution order\n4. **Enable debug mode** - Use `--debug` flag\n\n### Vite Plugin Fails\n\nVite plugins may rely on Vite-specific APIs:\n\n1. **Find Rollup equivalent** - Look for Rollup version of plugin\n2. **Use Unplugin version** - Check for `unplugin-*` alternative\n3. **Wait for support** - Vite plugin support improving\n\n## Resources\n\n- [Rolldown Plugin Development](https://rolldown.rs/apis/plugin-api)\n- [Unplugin Documentation](https://unplugin.unjs.io/)\n- [Rollup Plugins](https://github.com/rollup/plugins)\n- [Vite Plugins](https://vitejs.dev/plugins/)\n\n## Tips\n\n1. **Prefer Rolldown plugins** for best compatibility\n2. **Use Unplugin** for cross-bundler support\n3. **Cast types** for Rollup/Vite plugins\n4. **Test thoroughly** when using cross-ecosystem plugins\n5. **Check plugin docs** for specific configuration\n6. **Write custom plugins** for unique needs\n\n## Related\n\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [Rolldown Options](advanced-rolldown-options.md) - Advanced Rolldown config\n- [React Recipe](recipe-react.md) - React setup with plugins\n- [Vue Recipe](recipe-vue.md) - Vue setup with plugins\n","isInternal":false,"tokens":1711,"sizeBytes":6754},{"name":"advanced-programmatic.md","path":".agents/skills/tsdown/references/advanced-programmatic.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/advanced-programmatic.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Programmatic Usage\n\nUse tsdown from JavaScript/TypeScript code.\n\n## Overview\n\ntsdown can be imported and used programmatically in your Node.js scripts, custom build tools, or automation workflows.\n\n## Basic Usage\n\n### Simple Build\n\n```ts\nimport { build } from 'tsdown'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### With Options\n\n```ts\nimport { build } from 'tsdown'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n dts: true,\n minify: true,\n sourcemap: true,\n clean: true,\n})\n```\n\n### In-Memory Output\n\nSet `write: false` to access generated chunks and assets without writing the\nbundle output to disk:\n\n```ts\nimport { build } from 'tsdown'\n\nconst bundles = await build({\n entry: ['src/index.ts'],\n format: 'esm',\n write: false,\n clean: false,\n})\n\nfor (const bundle of bundles) {\n for (const output of bundle.chunks) {\n const contents = output.type === 'chunk' ? output.code : output.source\n console.log(output.fileName, contents)\n }\n}\n```\n\n`build()` currently returns a `TsdownBundle[]`, with one bundle for each\nresolved configuration. Even a single configuration returns an array; its\nin-memory Rolldown outputs are available in `bundle.chunks`.\n\nThe `write` option controls Rolldown's bundle output, while other file operations\nare configured separately. For example, `clean` defaults to `true`, so set\n`clean: false` as above if existing output directories must remain untouched.\nExplicitly enabled features such as `copy` or `exports` may still write files.\n`write: false` is incompatible with watch mode.\n\n## API Reference\n\n### build()\n\nMain function to run a build.\n\n```ts\nimport { build } from 'tsdown'\n\nawait build(options)\n```\n\n**Parameters:**\n- `options` - Build configuration object (same as config file)\n\n**Returns:**\n- `Promise` - One bundle for each resolved configuration\n\n**Throws:**\n- Build errors if compilation fails\n\n## Configuration Object\n\nAll config file options are available:\n\n```ts\nimport { build, defineConfig } from 'tsdown'\n\nconst config = defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: true,\n sourcemap: true,\n deps: {\n neverBundle: ['react', 'react-dom'],\n },\n plugins: [/* plugins */],\n hooks: {\n 'build:done': async () => {\n console.log('Build complete!')\n },\n },\n})\n\nawait build(config)\n```\n\nSee [Config Reference](option-config-file.md) for all options.\n\n## Common Patterns\n\n### Custom Build Script\n\n```ts\n// scripts/build.ts\nimport { build } from 'tsdown'\n\nasync function main() {\n console.log('Building library...')\n\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n })\n\n console.log('Build complete!')\n}\n\nmain().catch(console.error)\n```\n\nRun with:\n```bash\ntsx scripts/build.ts\n```\n\n### Multiple Builds\n\n```ts\nimport { build } from 'tsdown'\n\n// Build main library\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n dts: true,\n})\n\n// Build CLI tool\nawait build({\n entry: ['src/cli.ts'],\n format: ['esm'],\n outDir: 'dist/bin',\n platform: 'node',\n shims: true,\n})\n```\n\n### Conditional Build\n\n```ts\nimport { build } from 'tsdown'\n\nconst isDev = process.env.NODE_ENV === 'development'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n clean: !isDev,\n})\n```\n\n### With Error Handling\n\n```ts\nimport { build } from 'tsdown'\n\ntry {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n })\n console.log('✅ Build successful')\n} catch (error) {\n console.error('❌ Build failed:', error)\n process.exit(1)\n}\n```\n\n### Automated Workflow\n\n```ts\nimport { build } from 'tsdown'\nimport { execSync } from 'child_process'\n\nasync function release() {\n // Clean\n console.log('Cleaning...')\n execSync('rm -rf dist')\n\n // Build\n console.log('Building...')\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: true,\n })\n\n // Test\n console.log('Testing...')\n execSync('npm test')\n\n // Publish\n console.log('Publishing...')\n execSync('npm publish')\n}\n\nrelease().catch(console.error)\n```\n\n### Build with Post-Processing\n\n```ts\nimport { build } from 'tsdown'\nimport { copyFileSync } from 'fs'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n hooks: {\n 'build:done': async () => {\n // Copy additional files\n copyFileSync('README.md', 'dist/README.md')\n copyFileSync('LICENSE', 'dist/LICENSE')\n console.log('Copied additional files')\n },\n },\n})\n```\n\n## Watch Mode\n\nUnfortunately, watch mode is not directly exposed in the programmatic API. Use the CLI for watch mode:\n\n```ts\n// Use CLI for watch mode\nimport { spawn } from 'child_process'\n\nspawn('tsdown', ['--watch'], {\n stdio: 'inherit',\n shell: true,\n})\n```\n\n## Integration Examples\n\n### With Task Runner\n\n```ts\n// gulpfile.js\nimport { build } from 'tsdown'\nimport gulp from 'gulp'\n\ngulp.task('build', async () => {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n })\n})\n\ngulp.task('watch', () => {\n return gulp.watch('src/**/*.ts', gulp.series('build'))\n})\n```\n\n### With Custom CLI\n\n```ts\n// scripts/cli.ts\nimport { build } from 'tsdown'\nimport { Command } from 'commander'\n\nconst program = new Command()\n\nprogram\n .command('build')\n .option('--prod', 'Production build')\n .action(async (options) => {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: options.prod,\n sourcemap: !options.prod,\n })\n })\n\nprogram.parse()\n```\n\n### With CI/CD\n\n```ts\n// .github/scripts/build.ts\nimport { build } from 'tsdown'\n\nconst isCI = process.env.CI === 'true'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: isCI,\n clean: true,\n})\n\n// Upload to artifact storage\nif (isCI) {\n // Upload dist/ to S3, etc.\n}\n```\n\n## TypeScript Support\n\n```ts\n// scripts/build.ts\nimport { build, type UserConfig } from 'tsdown'\n\nconst config: UserConfig = {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n}\n\nawait build(config)\n```\n\n## Tips\n\n1. **Use TypeScript** for type safety\n2. **Handle errors** properly\n3. **Use hooks** for custom logic\n4. **Log progress** for visibility\n5. **Use CLI for watch** mode\n6. **Exit on error** in scripts\n\n## Troubleshooting\n\n### Import Errors\n\nEnsure tsdown is installed:\n```bash\npnpm add -D tsdown\n```\n\n### Type Errors\n\nImport types:\n```ts\nimport type { UserConfig } from 'tsdown'\n```\n\n### Build Fails Silently\n\nAdd error handling:\n```ts\ntry {\n await build(config)\n} catch (error) {\n console.error(error)\n process.exit(1)\n}\n```\n\n### Options Not Working\n\nCheck spelling and types:\n```ts\n// ✅ Correct\n{ format: ['esm', 'cjs'] }\n\n// ❌ Wrong\n{ formats: ['esm', 'cjs'] }\n```\n\n## Related\n\n- [Config File](option-config-file.md) - Configuration options\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [CLI](reference-cli.md) - Command-line interface\n- [Plugins](advanced-plugins.md) - Plugin system\n","isInternal":false,"tokens":1958,"sizeBytes":7127},{"name":"advanced-rolldown-options.md","path":".agents/skills/tsdown/references/advanced-rolldown-options.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/advanced-rolldown-options.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Customizing Rolldown Options\n\nPass options directly to the underlying Rolldown bundler.\n\n## Overview\n\ntsdown uses [Rolldown](https://rolldown.rs) as its core bundling engine. You can override Rolldown's input and output options directly for fine-grained control.\n\n**Warning:** You should be familiar with Rolldown's behavior before overriding options. Refer to the [Rolldown Config Options](https://rolldown.rs/reference/InputOptions.input) documentation.\n\n## Input Options\n\n### Using an Object\n\n```ts\nexport default defineConfig({\n inputOptions: {\n cwd: './custom-directory',\n },\n})\n```\n\n### Using a Function\n\nDynamically modify options based on the output format:\n\n```ts\nexport default defineConfig({\n inputOptions(inputOptions, format) {\n inputOptions.cwd = './custom-directory'\n return inputOptions\n },\n})\n```\n\n## Output Options\n\n### Using an Object\n\n```ts\nexport default defineConfig({\n outputOptions: {\n legalComments: 'inline',\n },\n})\n```\n\n### Using a Function\n\n```ts\nexport default defineConfig({\n outputOptions(outputOptions, format) {\n if (format === 'esm') {\n outputOptions.legalComments = 'inline'\n }\n return outputOptions\n },\n})\n```\n\n## Common Use Cases\n\n### Preserve Legal Comments\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outputOptions: {\n legalComments: 'inline',\n },\n})\n```\n\n### Custom Working Directory\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n inputOptions: {\n cwd: './packages/my-lib',\n },\n})\n```\n\n### Format-Specific Options\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outputOptions(outputOptions, format) {\n if (format === 'esm') {\n outputOptions.legalComments = 'inline'\n }\n return outputOptions\n },\n})\n```\n\n## When to Use\n\n- When tsdown doesn't expose a specific Rolldown option\n- For format-specific Rolldown customizations\n- For advanced bundling scenarios\n\n## Tips\n\n1. **Read Rolldown docs** before overriding options\n2. **Use functions** for format-specific customization\n3. **Test thoroughly** when overriding defaults\n4. **Prefer tsdown options** when available (e.g., use `minify` instead of setting it via `outputOptions`)\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [Config File](option-config-file.md) - Configuration options\n","isInternal":false,"tokens":577,"sizeBytes":2383},{"name":"guide-getting-started.md","path":".agents/skills/tsdown/references/guide-getting-started.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/guide-getting-started.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Getting Started\n\nQuick guide to installing and using tsdown for the first time.\n\n## Installation\n\nInstall tsdown as a development dependency:\n\n```bash\npnpm add -D tsdown\n\n# Optionally install TypeScript if not using isolatedDeclarations\npnpm add -D typescript\n```\n\n**Requirements:**\n- Node.js 22.18.0 or higher **to run tsdown** (build-time only)\n- Experimental support for Deno and Bun\n\n> [!NOTE]\n> The Node.js 22.18+ requirement only applies to the environment that runs `tsdown` itself. The **bundled output** can target much lower Node.js versions via the [`target`](./option-target.md) option, so libraries built with tsdown are not locked to Node.js 22+ at runtime.\n>\n> If your package needs to support Node.js 18 / 20, the recommended workflow is to **build with Node.js 22+ in CI**, then **test the built output (or the packed tarball) against the lower Node.js versions** you intend to support.\n\n## Quick Start Templates\n\nUse `create-tsdown` CLI for instant setup:\n\n```bash\npnpm create tsdown@latest\n```\n\nProvides templates for:\n- Pure TypeScript libraries\n- React component libraries\n- Vue component libraries\n- Ready-to-use configurations\n\n## First Bundle\n\n### 1. Create Source Files\n\n```ts\n// src/index.ts\nimport { hello } from './hello.ts'\nhello()\n\n// src/hello.ts\nexport function hello() {\n console.log('Hello tsdown!')\n}\n```\n\n### 2. Create Config File\n\n```ts\n// tsdown.config.ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n})\n```\n\n### 3. Run Build\n\n```bash\n./node_modules/.bin/tsdown\n```\n\nOutput: `dist/index.mjs`\n\n### 4. Test Output\n\n```bash\nnode dist/index.mjs\n# Output: Hello tsdown!\n```\n\n## Add to npm Scripts\n\n```json\n{\n \"scripts\": {\n \"build\": \"tsdown\"\n }\n}\n```\n\nRun with:\n\n```bash\npnpm build\n```\n\n## CLI Commands\n\n```bash\n# Check version\ntsdown --version\n\n# View help\ntsdown --help\n\n# Build with watch mode\ntsdown --watch\n\n# Build with specific format\ntsdown --format esm,cjs\n\n# Generate type declarations\ntsdown --dts\n```\n\n## Basic Configurations\n\n### TypeScript Library (ESM + CJS)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### Browser Library (IIFE)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n globalName: 'MyLib',\n platform: 'browser',\n minify: true,\n})\n```\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n## Using Plugins\n\nAdd Rolldown, Rollup, or Unplugin plugins:\n\n```ts\nimport SomePlugin from 'some-plugin'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [SomePlugin()],\n})\n```\n\n## Watch Mode\n\nEnable automatic rebuilds on file changes:\n\n```bash\ntsdown --watch\n# or\ntsdown -w\n```\n\n## Next Steps\n\n- Configure [entry points](option-entry.md) with glob patterns\n- Set up [multiple output formats](option-output-format.md)\n- Enable [type declaration generation](option-dts.md)\n- Explore [plugins](advanced-plugins.md) for extended functionality\n- Read [migration guide](guide-migrate-from-tsup.md) if coming from tsup\n","isInternal":false,"tokens":860,"sizeBytes":3210},{"name":"guide-introduction.md","path":".agents/skills/tsdown/references/guide-introduction.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/guide-introduction.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Introduction\n\n**tsdown** is _The Elegant Library Bundler_ — a fast, simple bundler for TypeScript and JavaScript libraries powered by Rolldown (Rust-based).\n\n## Why tsdown?\n\nBuilt on [Rolldown](https://rolldown.rs), tsdown provides a complete out-of-the-box solution for library authors:\n\n- **Simplified Configuration**: Sensible defaults for library development, minimal boilerplate\n- **Library-Specific Features**: Auto TypeScript declarations, multiple output formats, package validation\n- **Future-Ready**: Official Rolldown project, foundation for Rolldown Vite's Library Mode\n\n## Plugin Ecosystem\n\nSupports the full Rolldown plugin ecosystem plus most Rollup plugins. See [Plugins](advanced-plugins.md).\n\n## What Can It Bundle?\n\n- **TypeScript/JavaScript**: `.ts`, `.js` with modern syntax\n- **TypeScript Declarations**: Auto-generate `.d.ts` files\n- **Multiple Formats**: `esm`, `cjs`, `iife`, `umd`\n- **Assets**: `.json`, `.wasm`, CSS files\n- Built-in tree shaking, minification, and source maps\n\n## Key Differences from Rolldown\n\ntsdown wraps Rolldown with library-specific features:\n- Auto-external `dependencies`, `peerDependencies`, and `optionalDependencies` from `package.json`\n- DTS generation\n- `package.json` exports field generation\n- Watch mode with keyboard shortcuts\n- CSS preprocessing pipeline\n- Executable bundling (SEA)\n\n## Prior Arts\n\nInspired by: Rollup, esbuild, tsup, unbuild. Powered by Rolldown.\n\n## Related\n\n- [Getting Started](guide-getting-started.md) - Installation and first build\n- [Migrate from tsup](guide-migrate-from-tsup.md) - Migration guide\n","isInternal":false,"tokens":382,"sizeBytes":1589},{"name":"guide-migrate-from-tsup.md","path":".agents/skills/tsdown/references/guide-migrate-from-tsup.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/guide-migrate-from-tsup.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Migrate from tsup\n\nMigration guide for switching from tsup to tsdown.\n\n## Overview\n\ntsdown is built on Rolldown (Rust-based) vs tsup's esbuild, providing faster and more powerful bundling while maintaining compatibility.\n\n## Automatic Migration\n\n### Single Package\n\n```bash\nnpx tsdown-migrate\n```\n\n### Monorepo\n\n```bash\n# Using glob patterns\nnpx tsdown-migrate packages/*\n\n# Multiple directories\nnpx tsdown-migrate packages/foo packages/bar\n```\n\n### Migration Options\n\n- `[...dirs]` - Directories to migrate (supports globs)\n- `--dry-run` or `-d` - Preview changes without modifying files\n- `--yes` or `-y` - Skip confirmation (required in non-interactive environments)\n- `--package-manager ` - Override package manager auto-detection\n- `--no-install` - Skip dependency installation\n\nFor non-interactive callers that install dependencies separately:\n\n```bash\nnpx tsdown-migrate --yes --no-install\n```\n\nWhen installation is enabled, the tool detects the package manager from the\nproject's `packageManager` field or lockfile. If detection fails without a TTY,\npass `--package-manager ` or `--no-install`.\n\n**Important:** Commit your changes before running migration.\n\n## Key Differences\n\n### Default Values\n\n| Option | tsup | tsdown |\n|--------|------|--------|\n| `format` | `['cjs']` | `['esm']` |\n| `clean` | `false` | `true` |\n| `dts` | `false` | Auto-enabled if `types`/`typings` in package.json |\n| `target` | Manual | Auto-read from `engines.node` in package.json |\n\n### Option Renames\n\n| tsup | tsdown |\n|------|--------|\n| `entryPoints` | `entry` |\n| `cjsInterop` | `cjsDefault` |\n| `esbuildPlugins` | `plugins` |\n| `outExtension` | `outExtensions` |\n| `skipNodeModulesBundle` | `deps: { neverBundle: true }` |\n| `publicDir` | `copy` |\n| `bundle: false` | `unbundle: true` |\n| `removeNodeProtocol: true` | `nodeProtocol: 'strip'` |\n| `injectStyle: true` | `css: { inject: true }` |\n\nThe old names were accepted (with deprecation warnings) up to tsdown v0.22.14 and have been removed since — v0.23+ silently ignores them, so a leftover tsup option won't error. Migrate in two stages: install `tsdown@0.22.14` first and resolve every deprecation warning (a warning-free build proves the mapping is complete), then upgrade to the latest version. The `tsdown-migrate` tool installs v0.22.14 for this reason.\n\n### Deprecated but Compatible Options\n\nThese tsup options still work but emit deprecation warnings and will be removed in a future version — migrate them immediately:\n\n| tsup (deprecated) | tsdown (preferred) |\n|-------------------|--------------------|\n| `external: [...]` | `deps: { neverBundle: [...] }` |\n| `noExternal: [...]` | `deps: { alwaysBundle: [...] }` |\n\ntsdown also adds `deps.onlyBundle` for whitelisting allowed bundled packages.\n\n### Unsupported Options\n\n| Option | Status | Alternative |\n|--------|--------|-------------|\n| `splitting: false` | Always enabled | Code splitting cannot be disabled |\n| `metafile` | Not available | Use `devtools: true` for bundle analysis via Vite DevTools |\n| `swc` | Not supported | tsdown uses oxc for transformation (built-in) |\n| `experimentalDts` | Superseded | Use the `dts` option instead |\n| `legacyOutput` | Not supported | No alternative |\n| `plugins` (tsup experimental) | Incompatible | Migrate to Rolldown plugins |\n\n### Plugin System\n\ntsdown uses Rolldown plugins instead of esbuild plugins. If you use unplugin plugins, update the import path:\n\n```ts\n// Before (tsup)\nimport plugin from 'unplugin-example/esbuild'\n// After (tsdown)\nimport plugin from 'unplugin-example/rolldown'\n```\n\n### Output Filename Differences\n\nFor IIFE builds, `tsdown` emits `[name].iife.js`; `tsup` commonly emitted `[name].global.js`. `outExtensions` customizes extensions or suffixes, but it does not remove `.iife` or `.umd`. Use `outputOptions.entryFileNames: '[name].global.js'` to preserve old IIFE filenames.\n\n### New Features in tsdown\n\n#### Node Protocol Control\n\n```ts\nexport default defineConfig({\n nodeProtocol: true, // Add node: prefix (fs → node:fs)\n nodeProtocol: 'strip', // Remove node: prefix (node:fs → fs)\n nodeProtocol: false, // Keep as-is (default)\n})\n```\n\n#### Better Workspace Support\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*', // Build all packages\n})\n```\n\n#### Other tsdown-Exclusive Features\n\n- **`exports`**: Auto-generate the `exports` field in `package.json` with `exports: true`\n- **`publint`** / **`attw`**: Validate your package for common issues and type correctness\n- **`exe`**: Bundle as a Node.js standalone executable (SEA) with `exe: true`\n- **`devtools`**: Vite DevTools integration for bundle analysis with `devtools: true`\n- **`hooks`**: Lifecycle hooks (`build:prepare`, `build:before`, `build:done`)\n- **`css`**: Full CSS pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, and code splitting\n- **`globImport`**: Support for `import.meta.glob` (Vite-style glob imports)\n\n## Migration Checklist\n\n1. **Backup your code** - Commit all changes\n2. **Run migration tool** - `npx tsdown-migrate`\n3. **Review changes** - Check modified config files\n4. **Update scripts** - Change `tsup` to `tsdown` in package.json\n5. **Test build** - Run `pnpm build` to verify\n6. **Adjust config** - Fine-tune based on your needs\n\n## Common Migration Patterns\n\n### Basic Library\n\n**Before (tsup):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs', 'esm'],\n dts: true,\n})\n```\n\n**After (tsdown):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'], // ESM now default\n dts: true,\n clean: true, // Now enabled by default\n})\n```\n\n### With Custom Target\n\n**Before (tsup):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n target: 'es2020',\n})\n```\n\n**After (tsdown):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n // target auto-reads from package.json engines.node\n // Or override explicitly:\n target: 'es2020',\n})\n```\n\n### CLI Scripts\n\n**Before (package.json):**\n```json\n{\n \"scripts\": {\n \"build\": \"tsup\",\n \"dev\": \"tsup --watch\"\n }\n}\n```\n\n**After (package.json):**\n```json\n{\n \"scripts\": {\n \"build\": \"tsdown\",\n \"dev\": \"tsdown --watch\"\n }\n}\n```\n\n## Feature Compatibility\n\n### Supported tsup Features\n\nMost tsup features are supported:\n- ✅ Multiple entry points\n- ✅ Multiple formats (ESM, CJS, IIFE, UMD)\n- ✅ TypeScript declarations\n- ✅ Source maps\n- ✅ Minification\n- ✅ Watch mode\n- ✅ External dependencies\n- ✅ Tree shaking\n- ✅ Shims\n- ✅ Plugins (Rollup compatible)\n\n### Missing Features\n\nSome tsup features are not yet available. Check [GitHub issues](https://github.com/rolldown/tsdown/issues) for status and request features.\n\n## Troubleshooting\n\n### Build Fails After Migration\n\n1. **Check Node.js version** - Requires Node.js 22.18.0+ to run tsdown itself. The bundled output can still target lower Node.js versions via `target`; if you need to support Node.js 18 / 20, build with Node.js 22+ in CI and test the produced output (or packed tarball) on the lower versions.\n2. **Install TypeScript** - Required for DTS generation\n3. **Review config changes** - Ensure format and options are correct\n4. **Check dependencies** - Verify all dependencies are installed\n\n### Different Output\n\n- **Format order** - tsdown defaults to ESM first\n- **Clean behavior** - tsdown cleans outDir by default\n- **Target** - tsdown auto-detects from package.json\n\n### Performance Issues\n\ntsdown should be faster than tsup. If not:\n1. Enable `isolatedDeclarations` for faster DTS generation\n2. Check for large dependencies being bundled\n3. Use `deps.neverBundle: true` if needed\n\n## Getting Help\n\n- [GitHub Issues](https://github.com/rolldown/tsdown/issues) - Report bugs or request features\n- [Documentation](https://tsdown.dev) - Full documentation\n- [Migration Tool](https://github.com/rolldown/tsdown/tree/main/packages/migrate) - Source code\n\n## Acknowledgements\n\ntsdown is heavily inspired by tsup and incorporates parts of its codebase. Thanks to [@egoist](https://github.com/egoist) and the tsup community.\n","isInternal":false,"tokens":2136,"sizeBytes":8087},{"name":"option-cjs-default.md","path":".agents/skills/tsdown/references/option-cjs-default.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-cjs-default.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# CJS Default Export\n\nControl how default exports are handled in CommonJS output.\n\n## Overview\n\nThe `cjsDefault` option improves compatibility when generating CommonJS **entry** modules. When enabled (default), entry modules with only a single default export use `module.exports = ...` instead of `exports.default = ...`.\n\n## Type\n\n```ts\ncjsDefault?: boolean // default: true\n```\n\n## Basic Usage\n\n### Enabled (Default)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n cjsDefault: true, // default behavior\n})\n```\n\n### Disabled\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n cjsDefault: false,\n})\n```\n\n## How It Works\n\n### With `cjsDefault: true` (Default)\n\nWhen your module has **only a single default export**, tsdown transforms:\n\n**Source:**\n```ts\n// src/index.ts\nexport default function greet() {\n console.log('Hello, world!')\n}\n```\n\n**Generated CJS:**\n```js\n// dist/index.cjs\nfunction greet() {\n console.log('Hello, world!')\n}\nmodule.exports = greet\n```\n\n**Generated Declaration:**\n```ts\n// dist/index.d.cts\ndeclare function greet(): void\nexport = greet\n```\n\nThis allows consumers to use `const greet = require('your-module')` directly.\n\n### With `cjsDefault: false`\n\nThe default export stays as `exports.default`:\n\n```js\n// dist/index.cjs\nfunction greet() {\n console.log('Hello, world!')\n}\nexports.default = greet\n```\n\nConsumers need `require('your-module').default`.\n\n## Entry Modules Only\n\n`cjsDefault` only applies to **explicit entry modules**. In [unbundle mode](option-unbundle.md), imported modules that are emitted as non-entry chunks keep named CJS exports such as `exports.default`. CJS is considered legacy and is supported in maintenance-only mode, so this behavior will not be extended to non-entry chunks.\n\nIf every source module is intended to be consumed independently, include all of them as entries:\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts'],\n root: 'src',\n format: 'cjs',\n unbundle: true,\n})\n```\n\n## When to Disable\n\n- When your module has both default and named exports\n- When you need consistent `exports.default` behavior\n- When consumers always use ESM imports\n\n## Tips\n\n1. **Leave enabled** for most libraries (default `true`)\n2. **Disable** if you have both default and named exports and need consistent behavior\n3. **Test CJS consumers** to verify compatibility\n\n## Related Options\n\n- [Output Format](option-output-format.md) - Module formats\n- [Shims](option-shims.md) - ESM/CJS compatibility\n","isInternal":false,"tokens":616,"sizeBytes":2527},{"name":"option-cleaning.md","path":".agents/skills/tsdown/references/option-cleaning.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-cleaning.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Output Directory Cleaning\n\nControl how the output directory is cleaned before builds.\n\n## Overview\n\nBy default, tsdown **cleans the output directory** before each build to remove stale files from previous builds.\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Clean enabled (default)\ntsdown\n\n# Disable cleaning\ntsdown --no-clean\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n clean: true, // Default\n})\n```\n\n## Behavior\n\n### With Cleaning (Default)\n\nBefore each build:\n1. All files in `outDir` are removed\n2. Fresh build starts with empty directory\n3. Only current build outputs remain\n\n**Benefits:**\n- No stale files\n- Predictable output\n- Clean slate each build\n\n### Without Cleaning\n\nBuild outputs are added to existing files:\n\n```ts\nexport default defineConfig({\n clean: false,\n})\n```\n\n**Use when:**\n- Multiple builds to same directory\n- Incremental builds\n- Preserving other files\n- Watch mode (faster rebuilds)\n\n## Common Patterns\n\n### Production Build\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n clean: true, // Ensure clean output\n minify: true,\n})\n```\n\n### Development Mode\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n clean: !options.watch, // Don't clean in watch mode\n sourcemap: options.watch,\n}))\n```\n\n### Multiple Builds\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true, // Clean once\n },\n {\n entry: ['src/cli.ts'],\n outDir: 'dist',\n clean: false, // Don't clean, add to same dir\n },\n])\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n clean: true, // Clean each package's dist\n})\n```\n\n### Preserve Static Files\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n clean: false, // Keep manually added files\n outDir: 'dist',\n})\n\n// Manually copy files first\n// Then run tsdown --no-clean\n```\n\n## Clean Patterns\n\n### Selective Cleaning\n\n```ts\nimport { rmSync } from 'fs'\n\nexport default defineConfig({\n clean: false, // Disable auto clean\n hooks: {\n 'build:prepare': () => {\n // Custom cleaning logic\n rmSync('dist/*.js', { force: true })\n // Keep other files\n },\n },\n})\n```\n\n### Clean Specific Directories\n\n```ts\nexport default defineConfig({\n clean: false,\n hooks: {\n 'build:prepare': async () => {\n const { rm } = await import('fs/promises')\n // Only clean specific subdirectories\n await rm('dist/esm', { recursive: true, force: true })\n await rm('dist/cjs', { recursive: true, force: true })\n // Keep dist/types\n },\n },\n})\n```\n\n## Watch Mode Behavior\n\nIn watch mode, cleaning behavior is important:\n\n### Clean on First Build Only\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n watch: options.watch,\n clean: !options.watch, // Only clean initial build\n}))\n```\n\n**Result:**\n- First build: Clean\n- Subsequent rebuilds: Incremental\n\n### Always Clean\n\n```ts\nexport default defineConfig({\n watch: true,\n clean: true, // Clean every rebuild\n})\n```\n\n**Trade-off:** Slower rebuilds, but always fresh output.\n\n## Tips\n\n1. **Leave enabled** for production builds\n2. **Disable in watch mode** for faster rebuilds\n3. **Use multiple configs** carefully with cleaning\n4. **Custom clean logic** via hooks if needed\n5. **Be cautious** - cleaning removes ALL files in outDir\n6. **Test cleaning** - ensure no important files are lost\n\n## Troubleshooting\n\n### Important Files Deleted\n\n- Don't put non-build files in outDir\n- Use separate directory for static files\n- Disable cleaning and manage manually\n\n### Stale Files in Output\n\n- Enable cleaning: `clean: true`\n- Or manually remove before build\n\n### Slow Rebuilds in Watch\n\n- Disable cleaning in watch mode\n- Use incremental builds\n\n## CLI Examples\n\n```bash\n# Default (clean enabled)\ntsdown\n\n# Disable cleaning\ntsdown --no-clean\n\n# Watch mode without cleaning\ntsdown --watch --no-clean\n\n# Multiple formats with cleaning\ntsdown --format esm,cjs --clean\n```\n\n## Examples\n\n### Safe Production Build\n\n```bash\n# Clean before build\nrm -rf dist\ntsdown --clean\n```\n\n### Incremental Development\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n watch: true,\n clean: false, // Faster rebuilds\n sourcemap: true,\n})\n```\n\n### Multi-Stage Build\n\n```ts\n// Stage 1: Clean and build main\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true,\n },\n {\n entry: ['src/utils.ts'],\n outDir: 'dist',\n clean: false, // Add to same directory\n },\n])\n```\n\n## Related Options\n\n- [Output Directory](option-output-directory.md) - Configure outDir\n- [Watch Mode](option-watch-mode.md) - Development workflow\n- [Hooks](advanced-hooks.md) - Custom clean logic\n- [Entry](option-entry.md) - Entry points\n","isInternal":false,"tokens":1257,"sizeBytes":4871},{"name":"option-config-file.md","path":".agents/skills/tsdown/references/option-config-file.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-config-file.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Configuration File\n\nCentralize and manage build settings with a configuration file.\n\n## Overview\n\ntsdown searches for config files automatically in the current directory and parent directories.\n\n## Supported File Names\n\ntsdown looks for these files (in order):\n- `tsdown.config.ts`\n- `tsdown.config.mts`\n- `tsdown.config.cts`\n- `tsdown.config.js`\n- `tsdown.config.mjs`\n- `tsdown.config.cjs`\n- `tsdown.config.json`\n- `tsdown.config`\n- `package.json` (in `tsdown` field)\n\n## Basic Configuration\n\n### TypeScript Config\n\n```ts\n// tsdown.config.ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### JavaScript Config\n\n```js\n// tsdown.config.js\nexport default {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n}\n```\n\n### JSON Config\n\n```json\n// tsdown.config.json\n{\n \"entry\": [\"src/index.ts\"],\n \"format\": [\"esm\", \"cjs\"],\n \"dts\": true\n}\n```\n\n### Package.json Config\n\n```json\n// package.json\n{\n \"name\": \"my-library\",\n \"tsdown\": {\n \"entry\": [\"src/index.ts\"],\n \"format\": [\"esm\", \"cjs\"],\n \"dts\": true\n }\n}\n```\n\n## Multiple Configurations\n\nBuild multiple outputs with different settings:\n\n```ts\nexport default defineConfig([\n {\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n platform: 'node',\n dts: true,\n },\n {\n entry: 'src/browser.ts',\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n minify: true,\n },\n])\n```\n\nEach configuration runs as a separate build.\n\n## Dynamic Configuration\n\nUse a function for conditional config:\n\n```ts\nexport default defineConfig((options) => {\n const isDev = options.watch\n\n return {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n clean: !isDev,\n }\n})\n```\n\nAvailable options:\n- `watch` - Whether watch mode is enabled\n- Other CLI flags passed to config\n\n## Config Loaders\n\nControl how TypeScript config files are loaded:\n\n### Auto Loader (Default)\n\nUses native TypeScript support if available, otherwise falls back to `unrun`:\n\n```bash\ntsdown # Uses auto loader\n```\n\n### Native Loader\n\nUses runtime's native TypeScript support (Node.js 22.18.0+, Bun, Deno):\n\n```bash\ntsdown --config-loader native\n```\n\n### tsx Loader\n\nUses [tsx](https://tsx.is/) library for loading via its tsImport API. Note: `tsx` is an optional peer dependency — install it manually first.\n\n```bash\npnpm add -D tsx\ntsdown --config-loader tsx\n```\n\n### Unrun Loader\n\nUses [unrun](https://gugustinette.github.io/unrun/) library for loading. Note: `unrun` is an optional peer dependency — install it manually first.\n\n```bash\npnpm add -D unrun\ntsdown --config-loader unrun\n```\n\n**Tip:** Use `tsx` or `unrun` loader if you need to load TypeScript configs without file extensions in Node.js.\n\n## Custom Config Path\n\nSpecify a custom config file location:\n\n```bash\ntsdown --config ./configs/build.config.ts\n# or\ntsdown -c custom-config.ts\n```\n\n## Disable Config File\n\nIgnore config files and use CLI options only:\n\n```bash\ntsdown --no-config src/index.ts --format esm\n```\n\n## Extend Vite/Vitest Config (Experimental)\n\nReuse existing Vite or Vitest configurations:\n\n```bash\n# Extend vite.config.*\ntsdown --from-vite\n\n# Extend vitest.config.*\ntsdown --from-vite vitest\n```\n\n**Note:** Only specific options like `resolve` and `plugins` are reused. Test thoroughly as this feature is experimental.\n\n## Workspace / Monorepo\n\nBuild multiple packages with a single config:\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nEach package directory matching the glob pattern will be built with the same configuration.\n\n## Common Patterns\n\n### Library with Multiple Builds\n\n```ts\nexport default defineConfig([\n // Node.js build\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n platform: 'node',\n dts: true,\n },\n // Browser build\n {\n entry: ['src/browser.ts'],\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n },\n])\n```\n\n### Development vs Production\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !options.watch,\n sourcemap: options.watch ? true : false,\n clean: !options.watch,\n}))\n```\n\n### Monorepo Root Config\n\n```ts\n// Root tsdown.config.ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n // Shared config for all packages\n})\n```\n\n### Per-Package Override\n\n```ts\n// packages/special/tsdown.config.ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm'], // Override: only ESM\n platform: 'browser', // Override: browser only\n})\n```\n\n## Config Precedence\n\nWhen multiple configs exist:\n\n1. CLI options (highest priority)\n2. Config file specified with `--config`\n3. Auto-discovered config files\n4. Package.json `tsdown` field\n5. Default values\n\n## Tips\n\n1. **Use TypeScript config** for type checking and autocomplete\n2. **Use defineConfig** helper for better DX\n3. **Export arrays** for multiple build configurations\n4. **Use functions** for dynamic/conditional configs\n5. **Keep configs simple** - prefer convention over configuration\n6. **Use workspace** for monorepo builds\n7. **Test experimental features** thoroughly before production use\n\n## Related Options\n\n- [Entry](option-entry.md) - Configure entry points\n- [Output Format](option-output-format.md) - Output formats\n- [Watch Mode](option-watch-mode.md) - Watch mode configuration\n","isInternal":false,"tokens":1477,"sizeBytes":5592},{"name":"option-copy.md","path":".agents/skills/tsdown/references/option-copy.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-copy.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Copy Files\n\nCopy static files and directories into the build output.\n\n## Overview\n\nThe `copy` option copies assets that should be distributed without being processed by the bundler — images, fonts, license files, etc.\n\n## Basic Usage\n\n### CLI\n\n```bash\ntsdown --copy public\n```\n\nWith the default `outDir` of `dist`, `public/favicon.svg` is copied to `dist/public/favicon.svg`.\n\n### Config File\n\n```ts\nexport default defineConfig({\n copy: 'public',\n})\n```\n\nMultiple paths, glob patterns, or object entries in an array:\n\n```ts\nexport default defineConfig({\n copy: [\n 'LICENSE',\n {\n from: ['public/**/*', '!public/**/*.map'],\n to: 'dist/assets',\n flatten: false,\n },\n ],\n})\n```\n\nGlob patterns support negation with a leading `!`.\n\n**Note:** Relative source and destination paths are resolved from the project root (`cwd`), not from `outDir`.\n\n## Object Options\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `from` | `string \\| string[]` | Required | Source path or glob pattern; arrays can include negated patterns |\n| `to` | `string` | `outDir` | Destination path, resolved from the project root |\n| `flatten` | `boolean` | `true` | Place matched files directly in `to`. Set `false` to preserve the directory structure below the first segment |\n| `rename` | `string \\| ((name, extension, fullPath) => string)` | — | Change the destination name. Callback receives the extension without a leading dot and the absolute path |\n| `verbose` | `boolean` | `false` | Log each copied source and destination |\n\n### Preserve Directory Structure\n\n```ts\nexport default defineConfig({\n copy: {\n from: 'assets/**/*',\n to: 'dist/public',\n flatten: false,\n },\n})\n```\n\n`assets/fonts/inter.woff2` → `dist/public/fonts/inter.woff2`.\n\n### Rename Copied Items\n\n```ts\nexport default defineConfig({\n copy: [\n { from: 'src/file.txt', to: 'dist', rename: 'file.md' },\n {\n from: 'src/file.txt',\n to: 'dist',\n rename: (name, extension) => `${name}-renamed.${extension}`,\n },\n ],\n})\n```\n\nCreates `dist/file.md` and `dist/file-renamed.txt`.\n\n## Dynamic Configuration\n\n`copy` can be a sync or async callback receiving the resolved tsdown config:\n\n```ts\nexport default defineConfig({\n copy: ({ outDir }) => ({\n from: ['assets/**/*', '!assets/**/*.map'],\n to: `${outDir}/assets`,\n flatten: false,\n }),\n})\n```\n\n## Build and Watch Behavior\n\n- Copying runs after the bundle output is produced; files are copied without passing through Rolldown transforms.\n- A top-level `copy` option runs only once for a multi-format build; a format-specific override can define `copy` again for that format.\n- In watch mode, matched source files are watched as build dependencies — changing one triggers a rebuild and copies the current files again.\n\n## Related Options\n\n- [Output Directory](option-output-directory.md) - Where output goes\n- [Cleaning](option-cleaning.md) - Output directory cleanup\n- [Watch Mode](option-watch-mode.md) - Watch mode behavior\n","isInternal":false,"tokens":732,"sizeBytes":3035},{"name":"option-css.md","path":".agents/skills/tsdown/references/option-css.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-css.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# CSS Support\n\n**Status: Experimental — API and behavior may change.**\n\nConfigure CSS handling including preprocessors, syntax lowering, minification, and code splitting.\n\n## Getting Started\n\nAll CSS support in `tsdown` is provided by the `@tsdown/css` package. Install it to enable CSS handling:\n\n```bash\nnpm install -D @tsdown/css\n```\n\nWhen `@tsdown/css` is installed, CSS processing is automatically enabled. Without it, encountering CSS files will result in an error.\n\n## CSS Import\n\nImport `.css` files from TypeScript/JavaScript — CSS is extracted into separate `.css` assets:\n\n```ts\n// src/index.ts\nimport './style.css'\nexport function greet() { return 'Hello' }\n```\n\nOutput: `index.mjs` + `index.css`\n\n### `@import` Inlining\n\nCSS `@import` statements are resolved and inlined automatically. No separate output files produced.\n\n### Inline CSS (`?inline`)\n\nAppend `?inline` to return processed CSS as a JS string instead of emitting a `.css` file:\n\n```ts\nimport './style.css' // → .css file\nimport css from './theme.css?inline' // → JS string\n```\n\nWorks with preprocessors too (`./foo.scss?inline`). Goes through full pipeline (preprocessors, @import inlining, lowering, minification). Tree-shakeable (`moduleSideEffects: false`).\n\n## CSS Pre-processors\n\nBuilt-in support for Sass, Less, and Stylus. Install the preprocessor:\n\n```bash\n# Sass (either one)\nnpm install -D sass-embedded # recommended, faster\nnpm install -D sass\n\n# Less\nnpm install -D less\n\n# Stylus\nnpm install -D stylus\n```\n\nThen import directly:\n\n```ts\nimport './style.scss'\nimport './theme.less'\nimport './global.styl'\n```\n\n### Preprocessor Options\n\n```ts\nexport default defineConfig({\n css: {\n preprocessorOptions: {\n scss: {\n additionalData: `$brand-color: #ff7e17;`,\n },\n less: {\n math: 'always',\n },\n stylus: {\n define: { '$brand-color': '#ff7e17' },\n },\n },\n },\n})\n```\n\n### `additionalData`\n\nInject code at the beginning of every preprocessor file:\n\n```ts\n// String form\nscss: {\n additionalData: `@use \"src/styles/variables\" as *;`,\n}\n\n// Function form\nscss: {\n additionalData: (source, filename) => {\n if (filename.includes('theme')) return source\n return `@use \"src/styles/variables\" as *;\\n${source}`\n },\n}\n```\n\n## CSS Minification\n\n```ts\nexport default defineConfig({\n css: {\n minify: true,\n },\n})\n```\n\nPowered by Lightning CSS.\n\n## CSS Target\n\nOverride the top-level `target` specifically for CSS:\n\n```ts\nexport default defineConfig({\n target: 'node18',\n css: {\n target: 'chrome90', // CSS-specific target\n },\n})\n```\n\nSet `css.target: false` to disable CSS syntax lowering entirely.\n\n## CSS Transformer\n\n`css.transformer` controls mutually exclusive CSS processing paths:\n\n- `'lightningcss'` (default): `@import` via Lightning CSS `bundleAsync()`, no PostCSS.\n- `'postcss'`: `@import` via `postcss-import`, PostCSS plugins applied, Lightning CSS for final transform only.\n\n```ts\nexport default defineConfig({\n css: {\n transformer: 'postcss',\n },\n})\n```\n\n### PostCSS Options\n\n```ts\nexport default defineConfig({\n css: {\n transformer: 'postcss',\n postcss: {\n plugins: [require('autoprefixer')],\n },\n // Or: postcss: './config' — path to search for postcss.config.js\n },\n})\n```\n\nAuto-detects PostCSS config from project root when `transformer` is `'postcss'` and `css.postcss` is omitted.\n\n## Lightning CSS (Syntax Lowering)\n\nInstall `lightningcss` to enable CSS syntax lowering based on your `target`:\n\n```bash\nnpm install -D lightningcss\n```\n\nWhen `target` is set (e.g., `target: 'chrome108'`), modern CSS features are automatically downleveled:\n\n```css\n/* Input */\n.foo { & .bar { color: red } }\n\n/* Output (chrome108) */\n.foo .bar { color: red }\n```\n\n### Custom Lightning CSS Options\n\n```ts\nimport { Features } from 'lightningcss'\n\nexport default defineConfig({\n css: {\n lightningcss: {\n targets: { chrome: 100 << 16 },\n include: Features.Nesting,\n },\n },\n})\n```\n\n`css.lightningcss.targets` takes precedence over both `target` and `css.target` for CSS.\n\n## CSS Modules\n\nFiles with `.module.css` (and `.module.scss`, `.module.less`, etc.) are treated as CSS modules — class names are scoped and exported as JS:\n\n```ts\nimport styles from './app.module.css'\nconsole.log(styles.title) // \"scoped_title_hash\"\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n css: {\n modules: {\n scopeBehaviour: 'local', // 'local' (default) | 'global'\n generateScopedName: '[hash]_[local]', // Lightning CSS pattern string\n localsConvention: 'camelCase', // 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly'\n },\n },\n})\n```\n\nSet `css.modules: false` to disable. Function-form `generateScopedName` requires `transformer: 'postcss'`.\n\n`localsConvention` also accepts a function compatible with Vite and\n`postcss-modules`:\n\n```ts\nexport default defineConfig({\n css: {\n modules: {\n localsConvention: (\n originalClassName,\n generatedClassName,\n inputFile,\n ) => originalClassName.replaceAll(/-([a-z0-9])/g, (_, c) => c.toUpperCase()),\n },\n },\n})\n```\n\nThe function form works with both CSS transformers and returns the JavaScript\nexport key.\n\n### Optional Dependencies (PostCSS path)\n\n```bash\nnpm install -D postcss postcss-modules\n```\n\n## Code Splitting\n\n### Merged (Default)\n\nAll CSS merged into a single file (default: `style.css`).\n\n```ts\nexport default defineConfig({\n css: {\n fileName: 'my-library.css', // Custom name (default: 'style.css')\n },\n})\n```\n\n### Per-Chunk Splitting\n\n```ts\nexport default defineConfig({\n css: {\n splitting: true, // Each JS chunk gets a corresponding .css file\n },\n})\n```\n\n## Preserving CSS Imports (`css.inject`)\n\nWhen enabled, JS output preserves `import` statements pointing to emitted CSS files. Consumers auto-import CSS alongside JS:\n\n```ts\nexport default defineConfig({\n css: {\n inject: true,\n },\n})\n```\n\n## PostCSS Optional Peer Dependencies\n\nWhen using `transformer: 'postcss'`, install these as needed:\n\n| Package | Purpose | Required When |\n|---------|---------|---------------|\n| `postcss` | Core PostCSS engine | Always (with `transformer: 'postcss'`) |\n| `postcss-import` | Resolve/inline `@import` | CSS uses `@import` |\n| `postcss-modules` | CSS modules (scoped classes) | Using `.module.css` files |\n\n```bash\nnpm install -D postcss postcss-import postcss-modules\n```\n\nAll declared as optional peer dependencies of `@tsdown/css`.\n\n## Options Reference\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `css.transformer` | `'postcss' \\| 'lightningcss'` | `'lightningcss'` | CSS processing pipeline |\n| `css.splitting` | `boolean` | `false` | Per-chunk CSS splitting |\n| `css.fileName` | `string` | `'style.css'` | Merged CSS file name |\n| `css.minify` | `boolean` | `false` | CSS minification |\n| `css.modules` | `object \\| false` | `{}` | CSS modules config, or `false` to disable |\n| `css.inject` | `boolean` | `false` | Preserve CSS imports in JS output |\n| `css.target` | `string \\| string[] \\| false` | _from `target`_ | CSS-specific lowering target |\n| `css.postcss` | `string \\| object` | — | PostCSS config path or inline options |\n| `css.preprocessorOptions` | `object` | — | Preprocessor options |\n| `css.lightningcss` | `object` | — | Lightning CSS options |\n\n## Related\n\n- [Target](option-target.md) - Configure syntax lowering targets\n- [Output Format](option-output-format.md) - Module output formats\n","isInternal":false,"tokens":1922,"sizeBytes":7530},{"name":"option-dependencies.md","path":".agents/skills/tsdown/references/option-dependencies.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-dependencies.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Dependencies\n\nControl how dependencies are bundled or externalized.\n\n## Overview\n\ntsdown intelligently handles dependencies to keep your library lightweight while ensuring all necessary code is included.\n\n## Default Behavior\n\n### Auto-Externalized\n\nThese are **NOT bundled** by default:\n\n- **`dependencies`** - Installed automatically with your package\n- **`peerDependencies`** - User must install manually\n- **`optionalDependencies`** - May or may not be installed depending on platform/config\n\n### Conditionally Bundled\n\nThese are **bundled ONLY if imported**:\n\n- **`devDependencies`** - Only if actually used in source code\n- **Phantom dependencies** - In node_modules but not in package.json\n\n## Configuration Options\n\nAll dependency options are grouped under the `deps` field:\n\n```ts\nexport default defineConfig({\n deps: {\n neverBundle: ['react', /^@myorg\\//],\n alwaysBundle: ['some-package'],\n onlyBundle: ['cac', 'bumpp'],\n onlyImport: ['cac'],\n resolveDepSubpath: true,\n },\n})\n```\n\n### `deps.neverBundle`\n\nMark dependencies as external (not bundled):\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: [\n 'react', // Single package\n 'react-dom',\n /^@myorg\\//, // Regex pattern (all @myorg/* packages)\n /^lodash/, // All lodash packages\n ],\n },\n})\n```\n\nSet to `true` to externalize ALL dependencies:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: true,\n },\n})\n```\n\n**Result:** Every import that follows npm package naming conventions is externalized as written, without being resolved. This is fast and even works when dependencies are not installed. Subpaths like `my-dep/utils` are preserved exactly unless `resolveDepSubpath` is enabled. Other non-relative imports (`#` subpath imports, path aliases like `~/`) are resolved: they stay external if they resolve into node_modules, and are bundled if they map to local files. Combine with `alwaysBundle` to bundle selected dependencies.\n\n### `deps.alwaysBundle`\n\nForce dependencies to be bundled:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n alwaysBundle: [\n 'some-package', // Bundle this even if in dependencies\n 'vendor-lib',\n ],\n },\n})\n```\n\n### `deps.onlyBundle`\n\nWhitelist of dependencies allowed to be bundled from node_modules. Throws an error if any unlisted dependency is bundled:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n onlyBundle: [\n 'cac', // Allow bundling cac\n 'bumpp', // Allow bundling bumpp\n /^my-utils/, // Regex patterns supported\n ],\n },\n})\n```\n\n**Behavior:**\n- **Array** (`['cac', /^my-/]`): Only matching dependencies can be bundled. Error for others.\n- **`false`**: Suppress all warnings about bundled dependencies.\n- **Not set** (default): Warns if any node_modules dependencies are bundled.\n\n**Note:** Include all sub-dependencies in the list, not just top-level imports.\n\n### `deps.onlyImport`\n\nWhitelist of packages the emitted output is allowed to import at runtime. Throws an error (listing all violations) if any chunk imports an unlisted package:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n onlyImport: [\n 'cac', // Also covers subpath imports like cac/deno\n /^my-utils/, // Regex patterns match the package name\n ],\n },\n})\n```\n\n**Behavior:**\n- Matching is based on the package name; subpath imports (`cac/deno`) match `cac`.\n- Node.js built-in modules are always allowed when `platform` is `node`.\n- Relative imports between code-split chunks are always allowed.\n- Declaration output (`.d.ts`) is checked too.\n\n**Limitation:** ES imports and dynamic `import()` expressions are checked. CJS `require()` calls are not detected.\n\n### `deps.resolveDepSubpath`\n\nBy default, tsdown preserves external dependency subpath imports as written. Enable `resolveDepSubpath` to resolve subpath imports to their actual package-relative paths when a package has no `exports` field. For example, `my-dep/functions/lt` may become `my-dep/functions/lt.js`, and `my-dep/folder` may become `my-dep/folder/index.js`.\n\n```ts\nexport default defineConfig({\n deps: {\n resolveDepSubpath: true, // default: false\n },\n})\n```\n\n## Common Patterns\n\n### React Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.tsx'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n 'react',\n 'react-dom',\n /^react\\//, // react/jsx-runtime, etc.\n ],\n },\n dts: true,\n})\n```\n\n### Utility Library with Shared Deps\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n alwaysBundle: ['lodash-es'],\n },\n dts: true,\n})\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n /^@mycompany\\//, // Don't bundle other workspace packages\n ],\n },\n dts: true,\n})\n```\n\n### CLI Tool (Bundle Everything)\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n format: ['esm'],\n platform: 'node',\n deps: {\n alwaysBundle: [/.*/],\n },\n shims: true,\n})\n```\n\n### Library with Specific Externals\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n 'vue',\n '@vue/runtime-core',\n '@vue/reactivity',\n ],\n },\n dts: true,\n})\n```\n\n## Declaration Files\n\nDependency handling for `.d.ts` files follows the same rules as JavaScript.\n\n### Complex Type Resolution\n\nUse TypeScript resolver for complex third-party types:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n dts: {\n resolver: 'tsc', // Use TypeScript resolver instead of Oxc\n },\n})\n```\n\n**When to use `tsc` resolver:**\n- Types in `@types/*` packages with non-standard naming (e.g., `@types/babel__generator`)\n- Complex type dependencies\n- Issues with default Oxc resolver\n\n**Trade-off:** `tsc` is slower but more compatible.\n\n## CLI Usage\n\n### Never Bundle\n\n```bash\ntsdown --deps.never-bundle react --deps.never-bundle react-dom\ntsdown --deps.never-bundle '/^@myorg\\/.*/'\n```\n\n## Migration from Deprecated Options\n\n| Deprecated Option | New Option |\n|---|---|\n| `external` | `deps.neverBundle` |\n| `noExternal` | `deps.alwaysBundle` |\n\n## Examples by Use Case\n\n### Framework Component\n\n```ts\n// Don't bundle framework\nexport default defineConfig({\n deps: {\n neverBundle: ['vue', 'react', 'solid-js', 'svelte'],\n },\n})\n```\n\n### Standalone App\n\n```ts\n// Bundle everything\nexport default defineConfig({\n deps: {\n alwaysBundle: [/.*/],\n },\n})\n```\n\n### Shared Library\n\n```ts\n// Bundle only specific utils\nexport default defineConfig({\n deps: {\n neverBundle: [/.*/], // External by default\n alwaysBundle: ['tiny-utils'], // Except this one\n },\n})\n```\n\n### Monorepo Package\n\n```ts\n// External workspace packages, bundle utilities\nexport default defineConfig({\n deps: {\n neverBundle: [\n /^@workspace\\//, // Other workspace packages\n 'react',\n 'react-dom',\n ],\n alwaysBundle: [\n 'lodash-es', // Bundle utility libraries\n ],\n },\n})\n```\n\n## Troubleshooting\n\n### Dependency Bundled Unexpectedly\n\nCheck if it's in `devDependencies` and imported. Move to `dependencies`:\n\n```json\n{\n \"dependencies\": {\n \"should-be-external\": \"^1.0.0\"\n }\n}\n```\n\nOr explicitly externalize:\n\n```ts\nexport default defineConfig({\n deps: {\n neverBundle: ['should-be-external'],\n },\n})\n```\n\n### Missing Dependency at Runtime\n\nEnsure it's in `dependencies`, `peerDependencies`, or `optionalDependencies`:\n\n```json\n{\n \"dependencies\": {\n \"needed-package\": \"^1.0.0\"\n }\n}\n```\n\nOr bundle it:\n\n```ts\nexport default defineConfig({\n deps: {\n alwaysBundle: ['needed-package'],\n },\n})\n```\n\n### Type Resolution Errors\n\nUse TypeScript resolver for complex types:\n\n```ts\nexport default defineConfig({\n dts: {\n resolver: 'tsc',\n },\n})\n```\n\n## Summary\n\n**Default behavior:**\n- `dependencies`, `peerDependencies`, & `optionalDependencies` → External\n- `devDependencies` & phantom deps → Bundled if imported\n\n**Override (under `deps`):**\n- `neverBundle` → Force external\n- `alwaysBundle` → Force bundled\n- `onlyBundle` → Whitelist bundled deps\n- `onlyImport` → Whitelist runtime imports in output\n- `neverBundle: true` → Externalize all dependencies\n- `resolveDepSubpath: true` → Resolve external dependency subpath imports to package-relative paths\n\n**Declaration files:**\n- Same bundling logic as JavaScript\n- Use `resolver: 'tsc'` for complex types\n\n## Tips\n\n1. **Keep dependencies external** for libraries\n2. **Bundle everything** for standalone CLIs\n3. **Use regex patterns** for namespaced packages\n4. **Check bundle size** to verify external/bundled split\n5. **Test with fresh install** to catch missing dependencies\n6. **Use tsc resolver** only when needed (slower)\n\n## Related Options\n\n- [External](option-dependencies.md) - This page\n- [Platform](option-platform.md) - Runtime environment\n- [Output Format](option-output-format.md) - Module formats\n- [DTS](option-dts.md) - Type declarations\n","isInternal":false,"tokens":2299,"sizeBytes":9247},{"name":"option-dts.md","path":".agents/skills/tsdown/references/option-dts.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-dts.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# TypeScript Declaration Files\n\nGenerate `.d.ts` type declaration files for your library.\n\n## Overview\n\ntsdown uses [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts) to generate and bundle TypeScript declaration files.\n\n**Requirements:**\n- TypeScript must be installed in your project\n\n## Enabling DTS Generation\n\n### Auto-Enabled\n\nDTS generation is **automatically enabled** if `package.json` contains:\n- `types` field, or\n- `typings` field\n\n### Manual Enable\n\n#### CLI\n\n```bash\ntsdown --dts\n```\n\n#### Config File\n\n```ts\nexport default defineConfig({\n dts: true,\n})\n```\n\n## Performance\n\n### With `isolatedDeclarations` (Recommended)\n\n**Extremely fast** - uses oxc-transform for generation.\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"isolatedDeclarations\": true\n }\n}\n```\n\n### Without `isolatedDeclarations`\n\nFalls back to TypeScript compiler. Reliable but slower.\n\n## Declaration Maps\n\nMap `.d.ts` files back to original `.ts` sources (useful for monorepos).\n\n### Enable in tsconfig.json\n\n```json\n{\n \"compilerOptions\": {\n \"declarationMap\": true\n }\n}\n```\n\n### Enable in tsdown Config\n\n```ts\nexport default defineConfig({\n dts: {\n sourcemap: true,\n },\n})\n```\n\n## Advanced Options\n\n### Custom Compiler Options\n\nOverride TypeScript compiler options:\n\n```ts\nexport default defineConfig({\n dts: {\n compilerOptions: {\n removeComments: false,\n },\n },\n})\n```\n\n## Build Process\n\n- **ESM format**: `.js` and `.d.ts` files generated in same build\n- **CJS format**: Separate build process for `.d.ts` files\n\n## Common Patterns\n\n### Basic Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nOutput:\n- `dist/index.mjs`\n- `dist/index.cjs`\n- `dist/index.d.ts`\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nOutput:\n- `dist/index.mjs`, `dist/index.cjs`, `dist/index.d.ts`\n- `dist/utils.mjs`, `dist/utils.cjs`, `dist/utils.d.ts`\n\n### With Monorepo Support\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: {\n sourcemap: true, // Enable declaration maps\n },\n})\n```\n\n### Fast Build (Isolated Declarations)\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"isolatedDeclarations\": true,\n \"declaration\": true,\n \"declarationMap\": true\n }\n}\n```\n\n```ts\n// tsdown.config.ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true, // Will use fast oxc-transform\n})\n```\n\n## Troubleshooting\n\n### Missing Types\n\nEnsure TypeScript is installed:\n\n```bash\npnpm add -D typescript\n```\n\n### Slow Generation\n\nEnable `isolatedDeclarations` in `tsconfig.json` for faster builds.\n\n### Declaration Errors\n\nCheck that all exports have explicit types (required for `isolatedDeclarations`).\n\n### Report Issues\n\nFor DTS-specific issues, report to [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts/issues).\n\n### Vue Support\n\nEnable Vue component type generation (requires `vue-tsc`):\n\n```ts\nexport default defineConfig({\n dts: {\n vue: true,\n },\n})\n```\n\n### Oxc Transform\n\nControl Oxc usage for declaration generation:\n\n```ts\nexport default defineConfig({\n dts: {\n oxc: true, // Use oxc-transform (fast, requires isolatedDeclarations)\n },\n})\n```\n\n### Custom TSConfig\n\nSpecify a different tsconfig for DTS generation:\n\n```ts\nexport default defineConfig({\n dts: {\n tsconfig: './tsconfig.build.json',\n },\n})\n```\n\n## Available DTS Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `sourcemap` | `boolean` | Generate declaration source maps |\n| `compilerOptions` | `object` | Override TypeScript compiler options |\n| `vue` | `boolean` | Enable Vue type generation (requires vue-tsc) |\n| `oxc` | `boolean` | Use oxc-transform for fast generation |\n| `tsconfig` | `string` | Path to tsconfig file |\n| `resolver` | `'oxc' \\| 'tsc'` | Module resolver: `'oxc'` (default, fast) or `'tsc'` (more compatible) |\n| `cjsDefault` | `boolean` | CJS default export handling |\n| `sideEffects` | `boolean` | Preserve side effects in declarations |\n\n## Tips\n\n1. **Always enable DTS** for TypeScript libraries\n2. **Use isolatedDeclarations** for fast builds\n3. **Enable declaration maps** in monorepos\n4. **Ensure explicit types** for all exports\n5. **Install TypeScript** as dev dependency\n\n## Related Options\n\n- [Entry](option-entry.md) - Configure entry points\n- [Output Format](option-output-format.md) - Multiple output formats\n- [Target](option-target.md) - JavaScript version\n","isInternal":false,"tokens":1234,"sizeBytes":4628},{"name":"option-entry.md","path":".agents/skills/tsdown/references/option-entry.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-entry.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Entry Points\n\nConfigure which files to bundle as entry points.\n\n## Overview\n\nEntry points are the starting files for the bundling process. Each entry point generates a separate bundle.\n\n## Usage Patterns\n\n### CLI\n\n```bash\n# Single entry\ntsdown src/index.ts\n\n# Multiple entries\ntsdown src/index.ts src/cli.ts\n\n# Glob patterns\ntsdown 'src/*.ts'\n```\n\n### Config File\n\n#### Single Entry\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n})\n```\n\n#### Multiple Entries (Array)\n\n```ts\nexport default defineConfig({\n entry: ['src/entry1.ts', 'src/entry2.ts'],\n})\n```\n\n#### Named Entries (Object)\n\n```ts\nexport default defineConfig({\n entry: {\n main: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n})\n```\n\nOutput files will match the keys:\n- `dist/main.mjs`\n- `dist/utils.mjs`\n- `dist/cli.mjs`\n\n## Glob Patterns\n\nMatch multiple files dynamically using glob patterns:\n\n### All TypeScript Files\n\n```ts\nexport default defineConfig({\n entry: 'src/**/*.ts',\n})\n```\n\n### Exclude Test Files\n\n```ts\nexport default defineConfig({\n entry: ['src/*.ts', '!src/*.test.ts'],\n})\n```\n\n### Object Entries with Glob Patterns\n\nUse glob wildcards (`*`) in both keys and values. The `*` in the key acts as a placeholder replaced with the matched file name (without extension):\n\n```ts\nexport default defineConfig({\n entry: {\n // Maps src/foo.ts → dist/lib/foo.js, src/bar.ts → dist/lib/bar.js\n 'lib/*': 'src/*.ts',\n },\n})\n```\n\n#### Negation Patterns in Object Entries\n\nValues can be an array with negation patterns (`!`):\n\n```ts\nexport default defineConfig({\n entry: {\n 'hooks/*': ['src/hooks/*.ts', '!src/hooks/index.ts'],\n },\n})\n```\n\nMultiple positive and negation patterns:\n\n```ts\nexport default defineConfig({\n entry: {\n 'utils/*': [\n 'src/utils/*.ts',\n 'src/utils/*.tsx',\n '!src/utils/index.ts',\n '!src/utils/internal.ts',\n ],\n },\n})\n```\n\n**Warning:** Multiple positive patterns in an array value must share the same base directory.\n\n### Mixed Entries\n\nMix strings, glob patterns, and object entries in an array:\n\n```ts\nexport default defineConfig({\n entry: [\n 'src/*',\n '!src/foo.ts',\n { main: 'index.ts' },\n { 'lib/*': ['src/*.ts', '!src/bar.ts'] },\n ],\n})\n```\n\nObject entries take precedence when output names conflict.\n\n### Windows Compatibility\n\nUse forward slashes `/` instead of backslashes `\\` on Windows:\n\n```ts\n// ✅ Correct\nentry: 'src/utils/*.ts'\n\n// ❌ Wrong on Windows\nentry: 'src\\\\utils\\\\*.ts'\n```\n\n## Common Patterns\n\n### Library with Main Export\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### Library with Multiple Exports\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n client: 'src/client.ts',\n server: 'src/server.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### CLI Tool\n\n```ts\nexport default defineConfig({\n entry: {\n cli: 'src/cli.ts',\n },\n format: ['esm'],\n platform: 'node',\n})\n```\n\n### Preserve Directory Structure\n\nUse with `unbundle: true` to keep file structure:\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n unbundle: true,\n format: ['esm'],\n dts: true,\n})\n```\n\nThis will output files matching the source structure:\n- `src/index.ts` → `dist/index.mjs`\n- `src/utils/helper.ts` → `dist/utils/helper.mjs`\n\n## Tips\n\n1. **Use glob patterns** for multiple related files\n2. **Use object syntax** for custom output names\n3. **Exclude test files** with negation patterns `!**/*.test.ts`\n4. **Combine with unbundle** to preserve directory structure\n5. **Use named entries** for better control over output filenames\n","isInternal":false,"tokens":962,"sizeBytes":3676},{"name":"option-exe.md","path":".agents/skills/tsdown/references/option-exe.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-exe.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Executable - `exe`\n\n**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html).\n\n## Requirements\n\n- Node.js >= 25.7.0\n- Not supported in Bun or Deno\n\n## Basic Usage\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: true,\n})\n```\n\n## Behavior When Enabled\n\n- Declaration file generation (`dts`) is disabled by default\n- Code splitting is disabled\n- Only single entry points are supported\n- Legacy CJS warnings are suppressed\n\n## Advanced Configuration\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n fileName: 'my-tool',\n seaConfig: {\n disableExperimentalSEAWarning: true,\n useCodeCache: true,\n useSnapshot: false,\n },\n },\n})\n```\n\n## `ExeOptions`\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `seaConfig` | `Omit` | Node.js configuration options |\n| `fileName` | `string \\| ((chunk) => string)` | Custom output file name (without `.exe` or platform suffixes) |\n| `targets` | `ExeTarget[]` | Cross-platform build targets (requires `@tsdown/exe`) |\n\n## `SeaConfig`\n\nSee [Node.js Single Executable Applications documentation](https://nodejs.org/api/single-executable-applications.html).\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `disableExperimentalSEAWarning` | `boolean` | `true` | Disable the experimental warning |\n| `useSnapshot` | `boolean` | `false` | Use V8 snapshot |\n| `useCodeCache` | `boolean` | `false` | Use V8 code cache |\n| `execArgv` | `string[]` | - | Extra Node.js arguments |\n| `execArgvExtension` | `'none' \\| 'env' \\| 'cli'` | `'env'` | How to extend execArgv |\n| `assets` | `Record` | - | Assets to embed |\n\n## Cross-Platform Builds\n\nInstall `@tsdown/exe` to build executables for multiple platforms from a single machine:\n\n```bash\npnpm add -D @tsdown/exe\n```\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [\n { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },\n { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },\n { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },\n ],\n },\n})\n```\n\nThis downloads the target platform's Node.js binary, caches it locally, and produces platform-suffixed output:\n\n```\ndist/\n cli-linux-x64\n cli-darwin-arm64\n cli-win-x64.exe\n```\n\n### `ExeTarget`\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `platform` | `'win' \\| 'darwin' \\| 'linux'` | Target OS (nodejs.org naming) |\n| `arch` | `'x64' \\| 'arm64'` | Target CPU architecture |\n| `nodeVersion` | `string` | Node.js version (must be `>=25.7.0`), or `'latest'` / `'latest-lts'` to resolve automatically |\n\n### Custom Node.js Index and Download URL\n\nWhen downloading Node.js binaries (e.g. behind a corporate proxy or using a mirror), you can customize the sources:\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [{ platform: 'linux', arch: 'x64', nodeVersion: 'latest-lts' }],\n // Index used to resolve 'latest' / 'latest-lts' versions\n nodeDistIndexUrl: 'https://mirrors.example.com/node/index.json', // default: https://nodejs.org/dist/index.json\n // Fully custom download URL per target\n getDownloadUrl: (target) =>\n `https://mirrors.example.com/node/v${target.nodeVersion}/node-v${target.nodeVersion}-${target.platform}-${target.arch}.tar.gz`,\n },\n})\n```\n\n### Caching\n\nDownloaded Node.js binaries are cached in system cache directories:\n- **macOS:** `~/Library/Caches/tsdown/node/`\n- **Linux:** `~/.cache/tsdown/node/`\n- **Windows:** `%LOCALAPPDATA%/tsdown/Caches/node/`\n\n## Platform Notes\n\n- On macOS, the executable is automatically codesigned (ad-hoc) for Gatekeeper compatibility\n- On Windows, the `.exe` extension is automatically appended\n- When `targets` is specified, `seaConfig.executable` is ignored\n\n## CLI\n\n```bash\ntsdown --exe\ntsdown src/cli.ts --exe\n```\n","isInternal":false,"tokens":1092,"sizeBytes":4024},{"name":"option-lint.md","path":".agents/skills/tsdown/references/option-lint.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-lint.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Package Validation (publint & attw)\n\nValidate your package configuration and type declarations before publishing.\n\n## Overview\n\ntsdown integrates with [publint](https://publint.dev/) and [Are the types wrong?](https://arethetypeswrong.github.io/) (attw) to catch common packaging issues. Both are optional dependencies.\n\n## Installation\n\n```bash\n# publint only\nnpm install -D publint\n\n# attw only\nnpm install -D @arethetypeswrong/core\n\n# both\nnpm install -D publint @arethetypeswrong/core\n```\n\n## publint\n\nChecks that `package.json` fields (`exports`, `main`, `module`, `types`) match your actual output files.\n\n### Enable\n\n```ts\nexport default defineConfig({\n publint: true,\n})\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n publint: {\n level: 'error', // 'warning' | 'error' | 'suggestion'\n },\n})\n```\n\n### CLI\n\n```bash\ntsdown --publint\n```\n\n## attw (Are the types wrong?)\n\nVerifies TypeScript declarations are correct across different module resolution strategies (`node10`, `node16`, `bundler`).\n\n### Enable\n\n```ts\nexport default defineConfig({\n attw: true,\n})\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n attw: {\n profile: 'node16', // 'strict' | 'node16' | 'esm-only'\n level: 'error', // 'warn' | 'error'\n ignoreRules: ['false-cjs', 'cjs-resolves-to-esm'],\n },\n})\n```\n\n### Profiles\n\n| Profile | Description |\n|---------|-------------|\n| `strict` | Requires all resolutions to pass (default) |\n| `node16` | Ignores `node10` resolution failures |\n| `esm-only` | Ignores `node10` and `node16-cjs` resolution failures |\n\n### Ignore Rules\n\nSuppress specific problem types with `ignoreRules`:\n\n| Rule | Description |\n|------|-------------|\n| `no-resolution` | Module could not be resolved |\n| `untyped-resolution` | Resolution succeeded but has no types |\n| `false-cjs` | Types indicate CJS but implementation is ESM |\n| `false-esm` | Types indicate ESM but implementation is CJS |\n| `cjs-resolves-to-esm` | CJS resolution points to an ESM module |\n| `fallback-condition` | A fallback/wildcard condition was used |\n| `cjs-only-exports-default` | CJS module only exports a default |\n| `named-exports` | Named exports mismatch between types and implementation |\n| `false-export-default` | Types declare a default export that doesn't exist |\n| `missing-export-equals` | Types are missing `export =` for CJS |\n| `unexpected-module-syntax` | File uses unexpected module syntax |\n| `internal-resolution-error` | Internal resolution error in type checking |\n\n### CLI\n\n```bash\ntsdown --attw\n```\n\n## CI Integration\n\nBoth tools support CI-aware options:\n\n```ts\nexport default defineConfig({\n publint: 'ci-only',\n attw: {\n enabled: 'ci-only',\n profile: 'node16',\n level: 'error',\n },\n})\n```\n\nBoth tools require a `package.json` in your project directory.\n\n## Related Options\n\n- [CI Environment](advanced-ci.md) - CI-aware option details\n- [Package Exports](option-package-exports.md) - Generate exports field\n","isInternal":false,"tokens":754,"sizeBytes":2967},{"name":"option-log-level.md","path":".agents/skills/tsdown/references/option-log-level.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-log-level.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Log Level\n\nControl the verbosity of build output.\n\n## Overview\n\nThe `logLevel` option controls how much information tsdown displays during the build process.\n\n## Type\n\n```ts\nlogLevel?: 'silent' | 'error' | 'warn' | 'info'\n```\n\n**Default:** `'info'`\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Suppress all output\ntsdown --log-level silent\n\n# Only show errors\ntsdown --log-level error\n\n# Show warnings and errors\ntsdown --log-level warn\n\n# Show all info (default)\ntsdown --log-level info\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'error',\n})\n```\n\n## Available Levels\n\n| Level | Shows | Use Case |\n|-------|-------|----------|\n| `silent` | Nothing | CI/CD pipelines, scripting |\n| `error` | Errors only | Minimal output |\n| `warn` | Warnings + errors | Standard CI/CD |\n| `info` | All messages | Development (default) |\n\n## Common Patterns\n\n### CI/CD Pipeline\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'error', // Only show errors in CI\n})\n```\n\n### Scripting\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'silent', // No output for automation\n})\n```\n\n## Fail on Warnings\n\nThe `failOnWarn` option controls whether warnings cause the build to exit with a non-zero code. Defaults to `false` — warnings never fail the build.\n\n```ts\nexport default defineConfig({\n failOnWarn: false, // Default: never fail on warnings\n // failOnWarn: true, // Always fail on warnings\n // failOnWarn: 'ci-only', // Fail on warnings only in CI\n})\n```\n\nSee [CI Environment](advanced-ci.md) for more about CI-aware options.\n\n## Suppressing Warnings\n\nThe `suppressWarnings` option silences warnings whose message matches a given pattern. This is useful for opting out of non-actionable notices (such as the TypeScript 7.0 experimental API warning) while keeping other warnings visible.\n\n### Type\n\n```ts\nsuppressWarnings?:\n | string\n | RegExp\n | Array\n | ((msg: string) => boolean)\n```\n\n- **string** – substring match\n- **RegExp** – regular expression match\n- **array** – matches if any entry matches\n- **function** – custom predicate\n\n### Usage\n\n```ts\nexport default defineConfig({\n suppressWarnings: [\n 'is experimental', // substring match\n /Circular dependency/, // regexp match\n ],\n // Or a predicate function:\n // suppressWarnings: (msg) => msg.includes('is experimental'),\n})\n```\n\nMatched warnings are dropped **before** `failOnWarn` is applied, so a suppressed warning will not fail the build even when `failOnWarn: true`.\n\n## Related Options\n\n- [CI Environment](advanced-ci.md) - CI-aware option details\n- [CLI Reference](reference-cli.md) - All CLI options\n- [Config File](option-config-file.md) - Configuration setup\n","isInternal":false,"tokens":695,"sizeBytes":2773},{"name":"option-minification.md","path":".agents/skills/tsdown/references/option-minification.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-minification.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Minification\n\nCompress code to reduce bundle size.\n\n## Overview\n\nMinification removes unnecessary characters (whitespace, comments) and optimizes code for production, reducing bundle size and improving load times.\n\n**Note:** Uses [Oxc minifier](https://oxc.rs/docs/contribute/minifier) internally. The minifier is currently in alpha.\n\n## Type\n\n```ts\nminify?: boolean | 'dce-only' | MinifyOptions\n```\n\n- `true` — Enable full minification (whitespace removal, mangling, compression)\n- `false` — Disable minification (default)\n- `'dce-only'` — Only perform dead code elimination without full minification\n- `MinifyOptions` — Pass detailed options to the Oxc minifier\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Enable minification\ntsdown --minify\n\n# Disable minification\ntsdown --no-minify\n```\n\n**Note:** The CLI `--minify` flag is a boolean toggle. For `'dce-only'` mode or advanced options, use the config file.\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n minify: true,\n})\n```\n\n### DCE-Only Mode\n\nRemove dead code without full minification (keeps readable output):\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n minify: 'dce-only',\n})\n```\n\n## Example Output\n\n### Without Minification\n\n```js\n// dist/index.mjs\nconst x = 1\n\nfunction hello(x$1) {\n console.log('Hello World')\n console.log(x$1)\n}\n\nhello(x)\n```\n\n### With Minification\n\n```js\n// dist/index.mjs\nconst e=1;function t(e){console.log(`Hello World`),console.log(e)}t(e);\n```\n\n## Common Patterns\n\n### Production Build\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: true,\n clean: true,\n})\n```\n\n### Conditional Minification\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: !options.watch, // Only minify in production\n}))\n```\n\n### Browser Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n minify: true,\n})\n```\n\n### Multiple Builds\n\n```ts\nexport default defineConfig([\n // Development build\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: false,\n outDir: 'dist/dev',\n },\n // Production build\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: true,\n outDir: 'dist/prod',\n },\n])\n```\n\n## CLI Examples\n\n```bash\n# Production build with minification\ntsdown --minify --clean\n\n# Multiple formats with minification\ntsdown --format esm --format cjs --minify\n\n# Conditional minification (only when not watching)\ntsdown --minify # Or omit --watch\n```\n\n## Tips\n\n1. **Use `minify: true`** for production builds\n2. **Use `'dce-only'`** to remove dead code while keeping output readable\n3. **Skip minification** during development for faster rebuilds\n4. **Combine with tree shaking** for best results\n5. **Test minified output** thoroughly (Oxc minifier is in alpha)\n\n## Troubleshooting\n\n### Minified Code Has Bugs\n\nOxc minifier is in alpha and may have issues:\n\n1. **Use DCE-only mode**: `minify: 'dce-only'`\n2. **Report bug** to [Oxc project](https://github.com/oxc-project/oxc/issues)\n3. **Disable minification**: `minify: false`\n\n### Unexpected Output\n\n- **Test unminified** first to isolate issue\n- **Check source maps** for debugging\n- **Verify target compatibility**\n\n## Related Options\n\n- [Tree Shaking](option-tree-shaking.md) - Remove unused code\n- [Target](option-target.md) - Syntax transformations\n- [Output Format](option-output-format.md) - Module formats\n- [Sourcemap](option-sourcemap.md) - Debug information\n","isInternal":false,"tokens":963,"sizeBytes":3570},{"name":"option-output-directory.md","path":".agents/skills/tsdown/references/option-output-directory.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-output-directory.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Output Directory\n\nConfigure the output directory for bundled files.\n\n## Overview\n\nBy default, tsdown outputs bundled files to the `dist` directory. You can customize this location using the `outDir` option.\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Default output to dist/\ntsdown\n\n# Custom output directory\ntsdown --out-dir build\ntsdown -d lib\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: 'build',\n})\n```\n\n## Common Patterns\n\n### Standard Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist', // Default\n dts: true,\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n├── index.cjs\n└── index.d.ts\n```\n\n### Separate Directories by Format\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n outDir: 'dist/esm',\n },\n {\n entry: ['src/index.ts'],\n format: ['cjs'],\n outDir: 'dist/cjs',\n },\n])\n```\n\n**Output:**\n```\ndist/\n├── esm/\n│ └── index.js\n└── cjs/\n └── index.js\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: 'lib', // Custom directory\n clean: true,\n})\n```\n\n### Build to Root\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: '.', // Output to project root (not recommended)\n clean: false, // Don't clean root!\n})\n```\n\n**Warning:** Be careful when outputting to root to avoid deleting important files.\n\n## Output Extensions\n\n### Custom Extensions\n\nUse `outExtensions` to control file extensions:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n outExtensions({ format }) {\n return {\n js: format === 'esm' ? '.mjs' : '.cjs',\n }\n },\n})\n```\n\n### Default Extensions\n\n| Format | Default Extension | With `type: \"module\"` |\n|--------|-------------------|----------------------|\n| `esm` | `.mjs` | `.js` |\n| `cjs` | `.cjs` | `.js` |\n| `iife` | `.iife.js` | `.iife.js` |\n| `umd` | `.umd.js` | `.umd.js` |\n\nFor IIFE/UMD builds, `outExtensions` customizes extensions or suffixes but does not remove the built-in `.iife` or `.umd` segment. Use `outputOptions.entryFileNames` for custom full filename patterns.\n\n### ESM with .js Extension\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm'],\n outExtensions: () => ({ js: '.js' }),\n})\n```\n\nRequires `\"type\": \"module\"` in package.json.\n\n## File Naming\n\n### Entry Names\n\nControl output filenames based on entry names:\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n },\n outDir: 'dist',\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n└── utils.mjs\n```\n\n### Glob Entry\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n outDir: 'dist',\n unbundle: true, // Preserve structure\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n├── utils/\n│ └── helper.mjs\n└── components/\n └── button.mjs\n```\n\n## Multiple Builds\n\n### Same Output Directory\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true, // Clean first\n },\n {\n entry: ['src/cli.ts'],\n outDir: 'dist',\n clean: false, // Don't clean again\n },\n])\n```\n\n### Different Output Directories\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist/lib',\n },\n {\n entry: ['src/cli.ts'],\n format: ['esm'],\n outDir: 'dist/bin',\n },\n])\n```\n\n## CLI Examples\n\n```bash\n# Default\ntsdown\n\n# Custom directory\ntsdown --out-dir build\ntsdown -d lib\n\n# Nested directory\ntsdown --out-dir dist/lib\n\n# With other options\ntsdown --out-dir build --format esm,cjs --dts\n```\n\n## Tips\n\n1. **Use default `dist`** for standard projects\n2. **Be careful with root** - avoid `outDir: '.'`\n3. **Clean before build** - use `clean: true`\n4. **Consistent naming** - match your project conventions\n5. **Separate by format** if needed for clarity\n6. **Check .gitignore** - ensure output dir is ignored\n\n## Troubleshooting\n\n### Files Not in Expected Location\n\n- Check `outDir` config\n- Verify build completed successfully\n- Look for typos in path\n\n### Files Deleted Unexpectedly\n\n- Check if `clean: true`\n- Ensure outDir doesn't overlap with source\n- Don't use root as outDir\n\n### Permission Errors\n\n- Check write permissions\n- Ensure directory isn't locked\n- Try different location\n\n## Related Options\n\n- [Cleaning](option-cleaning.md) - Clean output directory\n- [Entry](option-entry.md) - Entry points\n- [Output Format](option-output-format.md) - Module formats\n- [Unbundle](option-unbundle.md) - Preserve structure\n","isInternal":false,"tokens":1327,"sizeBytes":4719},{"name":"option-output-format.md","path":".agents/skills/tsdown/references/option-output-format.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/option-output-format.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Output Format\n\nConfigure the module format(s) for generated bundles.\n\n## Overview\n\ntsdown can generate bundles in multiple formats. Default is ESM.\n\n## Available Formats\n\n| Format | Description | Use Case |\n|--------|-------------|----------|\n| `esm` | ECMAScript Module (default) | Modern Node.js, browsers, Deno |\n| `cjs` | CommonJS | Legacy Node.js, require() |\n| `iife` | Immediately Invoked Function Expression | Browser `\n\n\n\n\n```\n\n### Export Components\n\n```ts\n// src/index.ts\nexport { default as Button } from './Button.vue'\nexport { default as Input } from './Input.vue'\nexport { default as Modal } from './Modal.vue'\n\n// Re-export types\nexport type { ButtonProps } from './Button.vue'\n```\n\n## Common Patterns\n\n### Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n platform: 'neutral',\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [\n Vue({\n isProduction: true,\n style: {\n trim: true,\n },\n }),\n ],\n dts: {\n vue: true,\n },\n clean: true,\n})\n```\n\n### Multiple Components\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n Button: 'src/Button.vue',\n Input: 'src/Input.vue',\n Modal: 'src/Modal.vue',\n },\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [Vue({ isProduction: true })],\n dts: { vue: true },\n})\n```\n\n### With Composition Utilities\n\n```ts\n// src/composables/useCounter.ts\nimport { ref } from 'vue'\n\nexport function useCounter(initial = 0) {\n const count = ref(initial)\n const increment = () => count.value++\n const decrement = () => count.value--\n return { count, increment, decrement }\n}\n```\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [Vue({ isProduction: true })],\n dts: { vue: true },\n})\n```\n\n### TypeScript Configuration\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"ESNext\",\n \"lib\": [\"ES2020\", \"DOM\", \"DOM.Iterable\"],\n \"jsx\": \"preserve\",\n \"moduleResolution\": \"bundler\",\n \"allowImportingTsExtensions\": true,\n \"strict\": true,\n \"isolatedDeclarations\": true,\n \"skipLibCheck\": true\n },\n \"include\": [\"src\"],\n \"exclude\": [\"node_modules\", \"dist\"]\n}\n```\n\n### Package.json Configuration\n\n```json\n{\n \"name\": \"my-vue-library\",\n \"version\": \"1.0.0\",\n \"type\": \"module\",\n \"main\": \"./dist/index.cjs\",\n \"module\": \"./dist/index.mjs\",\n \"types\": \"./dist/index.d.ts\",\n \"exports\": {\n \".\": {\n \"types\": \"./dist/index.d.ts\",\n \"import\": \"./dist/index.mjs\",\n \"require\": \"./dist/index.cjs\"\n },\n },\n \"files\": [\"dist\"],\n \"peerDependencies\": {\n \"vue\": \"^3.0.0\"\n },\n \"devDependencies\": {\n \"tsdown\": \"^0.9.0\",\n \"typescript\": \"^5.0.0\",\n \"unplugin-vue\": \"^5.0.0\",\n \"vue\": \"^3.4.0\",\n \"vue-tsc\": \"^2.0.0\"\n }\n}\n```\n\n## Advanced Patterns\n\n### With Vite Plugins\n\nSome Vite Vue plugins may work:\n\n```ts\nimport Vue from 'unplugin-vue/rolldown'\nimport Components from 'unplugin-vue-components/rolldown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [\n Vue({ isProduction: true }),\n Components({\n dts: 'src/components.d.ts',\n }),\n ],\n dts: { vue: true },\n})\n```\n\n### JSX Support\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue'],\n },\n plugins: [\n Vue({\n isProduction: true,\n script: {\n propsDestructure: true,\n },\n }),\n ],\n inputOptions: {\n transform: {\n jsx: 'automatic',\n jsxImportSource: 'vue',\n },\n },\n dts: { vue: true },\n})\n```\n\n### Monorepo Vue Packages\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: ['vue', /^@mycompany\\//],\n },\n plugins: [Vue({ isProduction: true })],\n dts: { vue: true },\n})\n```\n\n## Plugin Options\n\n### unplugin-vue Options\n\n```ts\nVue({\n isProduction: true,\n script: {\n defineModel: true,\n propsDestructure: true,\n },\n style: {\n trim: true,\n },\n template: {\n compilerOptions: {\n isCustomElement: (tag) => tag.startsWith('custom-'),\n },\n },\n})\n```\n\n## Tips\n\n1. **Always externalize Vue** - Don't bundle Vue itself\n2. **Enable vue: true in dts** - For proper type generation\n3. **Use platform: 'neutral'** - Maximum compatibility\n4. **Install vue-tsc** - Required for type generation\n5. **Set isProduction: true** - Optimize for production\n6. **Add peer dependency** - Vue as peer dependency\n\n## Troubleshooting\n\n### Type Generation Fails\n\nEnsure vue-tsc is installed:\n```bash\npnpm add -D vue-tsc\n```\n\nEnable in config:\n```ts\ndts: { vue: true }\n```\n\n### Component Types Missing\n\nCheck TypeScript config:\n```json\n{\n \"compilerOptions\": {\n \"jsx\": \"preserve\",\n \"moduleResolution\": \"bundler\"\n }\n}\n```\n\n### Vue Not Externalized\n\nAdd to deps.neverBundle:\n```ts\ndeps: {\n neverBundle: ['vue'],\n}\n```\n\n### SFC Compilation Errors\n\nCheck unplugin-vue version:\n```bash\npnpm add -D unplugin-vue@latest\n```\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Dependencies](option-dependencies.md) - External packages\n- [DTS](option-dts.md) - Type declarations\n- [React Recipe](recipe-react.md) - React component libraries\n","isInternal":false,"tokens":1862,"sizeBytes":6562},{"name":"recipe-wasm.md","path":".agents/skills/tsdown/references/recipe-wasm.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/recipe-wasm.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# WASM Support\n\nBundle WebAssembly modules in your TypeScript/JavaScript project.\n\n## Overview\n\ntsdown supports WASM through [`rolldown-plugin-wasm`](https://github.com/sxzz/rolldown-plugin-wasm), enabling direct `.wasm` imports with synchronous and asynchronous instantiation.\n\n## Setup\n\n### Install\n\n```bash\npnpm add -D rolldown-plugin-wasm\n```\n\n### Configure\n\n```ts\nimport { wasm } from 'rolldown-plugin-wasm'\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n plugins: [wasm()],\n})\n```\n\n### TypeScript Support\n\nAdd type declarations to `tsconfig.json`:\n\n```jsonc\n{\n \"compilerOptions\": {\n \"types\": [\"rolldown-plugin-wasm/types\"]\n }\n}\n```\n\n## Importing WASM Modules\n\n### Direct Import\n\n```ts\nimport { add } from './add.wasm'\nadd(1, 2)\n```\n\n### Async Init\n\nUse `?init` query for async initialization:\n\n```ts\nimport init from './add.wasm?init'\nconst instance = await init(imports) // imports optional\ninstance.exports.add(1, 2)\n```\n\n### Sync Init\n\nUse `?init&sync` query for synchronous initialization:\n\n```ts\nimport initSync from './add.wasm?init&sync'\nconst instance = initSync(imports) // imports optional\ninstance.exports.add(1, 2)\n```\n\n## wasm-bindgen Support\n\n### Target `bundler` (Recommended)\n\n```ts\nimport { add } from 'some-pkg'\nadd(1, 2)\n```\n\n### Target `web` (Node.js)\n\n```ts\nimport { readFile } from 'node:fs/promises'\nimport init, { add } from 'some-pkg'\nimport wasmUrl from 'some-pkg/add_bg.wasm?url'\n\nawait init({\n module_or_path: readFile(new URL(wasmUrl, import.meta.url)),\n})\nadd(1, 2)\n```\n\n### Target `web` (Browser)\n\n```ts\nimport init, { add } from 'some-pkg/add.js'\nimport wasmUrl from 'some-pkg/add_bg.wasm?url'\n\nawait init({ module_or_path: wasmUrl })\nadd(1, 2)\n```\n\n`nodejs` and `no-modules` wasm-bindgen targets are not supported.\n\n## Plugin Options\n\n```ts\nwasm({\n maxFileSize: 14 * 1024, // Max size for inline (default: 14KB)\n fileName: '[hash][extname]', // Output file name pattern\n targetEnv: 'auto', // 'auto' | 'auto-inline' | 'browser' | 'node'\n})\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `maxFileSize` | `14 * 1024` | Max file size for inlining. Set to `0` to always copy. |\n| `fileName` | `'[hash][extname]'` | Pattern for emitted WASM files |\n| `targetEnv` | `'auto'` | `'auto'` detects at runtime; `'browser'` omits Node builtins; `'node'` omits fetch |\n\n## Related Options\n\n- [Plugins](advanced-plugins.md) - Plugin system overview\n- [Platform](option-platform.md) - Target platform configuration\n","isInternal":false,"tokens":717,"sizeBytes":2535},{"name":"reference-cli.md","path":".agents/skills/tsdown/references/reference-cli.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/references/reference-cli.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# CLI Reference\n\nComplete reference for tsdown command-line interface.\n\n## Overview\n\nAll CLI flags can also be set in the config file. CLI flags override config file options.\n\n## Flag Patterns\n\nCLI flag mapping rules:\n- `--foo` sets `foo: true`\n- `--no-foo` sets `foo: false`\n- `--foo.bar` sets `foo: { bar: true }`\n- `--format esm --format cjs` sets `format: ['esm', 'cjs']`\n\nCLI flags support both camelCase and kebab-case. For example, `--outDir` and `--out-dir` are equivalent.\n\n## Basic Commands\n\n### Build\n\n```bash\n# Build with default config\ntsdown\n\n# Build specific files\ntsdown src/index.ts src/cli.ts\n\n# Build with watch mode\ntsdown --watch\n```\n\n## Configuration\n\n### `--config, -c `\n\nSpecify custom config file:\n\n```bash\ntsdown --config build.config.ts\ntsdown -c custom-config.js\n```\n\n### `--no-config`\n\nDisable config file loading:\n\n```bash\ntsdown --no-config src/index.ts\n```\n\n### `--config-loader `\n\nChoose config loader (`auto`, `native`, `tsx`, `unrun`). `tsx` and `unrun` are optional peer dependencies — install them manually first:\n\n```bash\ntsdown --config-loader tsx\ntsdown --config-loader unrun\n```\n\n### `--tsconfig `\n\nSpecify TypeScript config file:\n\n```bash\ntsdown --tsconfig tsconfig.build.json\n```\n\n## Entry Points\n\n### `[...files]`\n\nSpecify entry files as arguments:\n\n```bash\ntsdown src/index.ts src/utils.ts\n```\n\n## Output Options\n\n### `--format `\n\nOutput format (`esm`, `cjs`, `iife`, `umd`):\n\n```bash\ntsdown --format esm\ntsdown --format esm --format cjs\n```\n\n### `--out-dir, -d `\n\nOutput directory:\n\n```bash\ntsdown --out-dir lib\ntsdown -d dist\n```\n\n### `--dts`\n\nGenerate TypeScript declarations:\n\n```bash\ntsdown --dts\n```\n\n### `--clean`\n\nClean output directory before build:\n\n```bash\ntsdown --clean\n```\n\n## Build Options\n\n### `--target `\n\nJavaScript target version:\n\n```bash\ntsdown --target es2020\ntsdown --target node18\ntsdown --target chrome100\ntsdown --no-target # Disable transformations\n```\n\n### `--platform `\n\nTarget platform (`node`, `browser`, `neutral`):\n\n```bash\ntsdown --platform node\ntsdown --platform browser\n```\n\n### `--minify`\n\nEnable minification:\n\n```bash\ntsdown --minify\ntsdown --no-minify\n```\n\n### `--sourcemap`\n\nGenerate source maps:\n\n```bash\ntsdown --sourcemap\ntsdown --sourcemap inline\n```\n\n### `--treeshake`\n\nEnable/disable tree shaking:\n\n```bash\ntsdown --treeshake\ntsdown --no-treeshake\n```\n\n## Dependencies\n\n### `--deps.never-bundle `\n\nMark module as external (not bundled):\n\n```bash\ntsdown --deps.never-bundle react --deps.never-bundle react-dom\n```\n\n### `--shims`\n\nAdd ESM/CJS compatibility shims:\n\n```bash\ntsdown --shims\n```\n\n## Development\n\n### `--watch, -w [path]`\n\nEnable watch mode:\n\n```bash\ntsdown --watch\ntsdown -w\ntsdown --watch src # Watch specific directory\n```\n\n### `--ignore-watch `\n\nIgnore paths in watch mode:\n\n```bash\ntsdown --watch --ignore-watch test\n```\n\n### `--on-success `\n\nRun command after successful build:\n\n```bash\ntsdown --watch --on-success \"echo Build complete!\"\n```\n\n## Environment Variables\n\n### `--env.* `\n\nSet compile-time environment variables:\n\n```bash\ntsdown --env.NODE_ENV=production --env.API_URL=https://api.example.com\n```\n\nAccess as `import.meta.env.*` or `process.env.*`.\n\n### `--env-file `\n\nLoad environment variables from file:\n\n```bash\ntsdown --env-file .env.production\n```\n\n### `--env-prefix `\n\nFilter environment variables by prefix (default: `TSDOWN_`):\n\n```bash\ntsdown --env-file .env --env-prefix APP_ --env-prefix TSDOWN_\n```\n\n## Assets\n\n### `--copy `\n\nCopy directory to output:\n\n```bash\ntsdown --copy public\ntsdown --copy assets --copy static\n```\n\n## Executable\n\n### `--exe`\n\n**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html). Requires Node.js >= 25.7.0, not supported in Bun or Deno. Cross-platform builds supported via `@tsdown/exe`.\n\n```bash\ntsdown --exe\n```\n\nWhen enabled:\n- Declaration file generation (`dts`) is disabled by default\n- Code splitting is disabled\n- Only single entry points are supported\n\nSee [Executable](option-exe.md) for advanced configuration and cross-platform builds.\n\n## Package Management\n\n### `--exports`\n\nGenerate the `exports` field in package.json:\n\n```bash\ntsdown --exports\n```\n\n### `--publint`\n\nEnable package validation:\n\n```bash\ntsdown --publint\n```\n\n### `--attw`\n\nEnable \"Are the types wrong\" validation:\n\n```bash\ntsdown --attw\n```\n\n### `--unused`\n\nCheck for unused dependencies:\n\n```bash\ntsdown --unused\n```\n\n## Logging\n\n### `--log-level `\n\nSet logging verbosity (`silent`, `error`, `warn`, `info`):\n\n```bash\ntsdown --log-level error\ntsdown --log-level warn\n```\n\n### `--report` / `--no-report`\n\nEnable/disable build report:\n\n```bash\ntsdown --no-report # Disable size report\ntsdown --report # Enable (default)\n```\n\n### `--debug [feat]`\n\nShow debug logs:\n\n```bash\ntsdown --debug\ntsdown --debug rolldown # Debug specific feature\n```\n\n## Integration\n\n### `--from-vite [vitest]`\n\nExtend Vite or Vitest config:\n\n```bash\ntsdown --from-vite # Use vite.config.*\ntsdown --from-vite vitest # Use vitest.config.*\n```\n\n## Workspace / Monorepo\n\n### `--workspace, -W [dir]`\n\nEnable workspace mode for building multiple packages:\n\n```bash\ntsdown -W\ntsdown -W packages/\n```\n\n### `--filter, -F `\n\nFilter configs by name or working directory. Supports regex:\n\n```bash\ntsdown -W -F my-package\ntsdown -W -F /^pkg-/\n```\n\n### `--concurrency `\n\nMaximum number of Rolldown builds to run in parallel. Defaults to unlimited:\n\n```bash\ntsdown -W --concurrency 4\n```\n\nNot supported in watch mode (ignored with a warning).\n\n### `--unbundle`\n\nEnable unbundle (bundleless) mode:\n\n```bash\ntsdown --unbundle\n```\n\n### `--root `\n\nSpecify the root directory of input files (similar to TypeScript's `rootDir`). Controls the output directory structure by determining how entry file paths map to output paths. Defaults to the common base directory of all entry files.\n\n```bash\ntsdown --root src\ntsdown --root .\n```\n\n### `--fail-on-warn`\n\nFail on warnings (enabled by default):\n\n```bash\ntsdown --no-fail-on-warn # Disable\n```\n\n## Common Usage Patterns\n\n### Basic Build\n\n```bash\ntsdown\n```\n\n### Library (ESM + CJS + Types)\n\n```bash\ntsdown --format esm --format cjs --dts --clean\n```\n\n### Production Build\n\n```bash\ntsdown --minify --clean --no-report\n```\n\n### Development (Watch)\n\n```bash\ntsdown --watch --sourcemap\n```\n\n### Browser Bundle (IIFE)\n\n```bash\ntsdown --format iife --platform browser --minify\n```\n\n### Node.js CLI Tool\n\n```bash\ntsdown --format esm --platform node --shims\n```\n\n### Standalone Executable\n\n```bash\ntsdown src/cli.ts --exe\n```\n\n### Monorepo Package\n\n```bash\ntsdown --clean --dts --exports --publint\n```\n\n### With Environment Variables\n\n```bash\ntsdown --env-file .env.production --env.BUILD_TIME=$(date +%s)\n```\n\n### Copy Assets\n\n```bash\ntsdown --copy public --copy assets --clean\n```\n\n## Tips\n\n1. **Use config file** for complex setups\n2. **CLI flags override** config file options\n3. **Chain multiple formats** for multi-target builds\n4. **Use --clean** to avoid stale files\n5. **Enable --dts** for TypeScript libraries\n6. **Use --watch** during development\n7. **Add --on-success** for post-build tasks\n8. **Use --exports** to auto-generate package.json fields\n\n## Related Documentation\n\n- [Config File](option-config-file.md) - Configuration file options\n- [Entry](option-entry.md) - Entry point configuration\n- [Output Format](option-output-format.md) - Format options\n- [Watch Mode](option-watch-mode.md) - Watch mode details\n","isInternal":false,"tokens":2086,"sizeBytes":7618},{"name":"SKILL.md","path":".agents/skills/tsdown/SKILL.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/.agents/skills/tsdown/SKILL.md","title":"tsdown","category":"anthropic-skill","format":"markdown","content":"---\nname: tsdown\ndescription: 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.\n---\n\n# tsdown - The Elegant Library Bundler\n\nBlazing-fast bundler for TypeScript/JavaScript libraries powered by Rolldown and Oxc.\n\n## Runtime Requirement\n\n`tsdown` requires **Node.js 22.18.0 or higher to run** (build-time only). However, the bundled output can target much lower Node.js versions via the [`target`](references/option-target.md) option, so libraries built with tsdown are **not locked to Node.js 22+ at runtime**.\n\nIf your package needs to support Node.js 18 / 20:\n\n- **Build with Node.js 22+ in CI** (e.g. set `target: 'node18'` or `target: 'node20'`).\n- **Test the built output (or the packed tarball) on the lower Node.js versions** you intend to support — e.g. using a matrix job that runs the published package's tests on Node.js 18 / 20 / 22.\n\n## When to Use\n\n- Building TypeScript/JavaScript libraries for npm\n- Generating TypeScript declaration files (.d.ts)\n- Bundling for multiple formats (ESM, CJS, IIFE, UMD)\n- Optimizing bundles with tree shaking and minification\n- Migrating from tsup with minimal changes\n- Building React, Vue, Solid, or Svelte component libraries\n\n## Quick Start\n\n```bash\n# Install\npnpm add -D tsdown\n\n# Basic usage\nnpx tsdown\n\n# With config file\nnpx tsdown --config tsdown.config.ts\n\n# Watch mode\nnpx tsdown --watch\n\n# Migrate from tsup\nnpx tsdown-migrate\n```\n\n## Basic Configuration\n\n```ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n## Core References\n\n| Topic | Description | Reference |\n|-------|-------------|-----------|\n| Getting Started | Installation, first bundle, CLI basics | [guide-getting-started](references/guide-getting-started.md) |\n| Configuration File | Config file formats, multiple configs, workspace | [option-config-file](references/option-config-file.md) |\n| CLI Reference | All CLI commands and options | [reference-cli](references/reference-cli.md) |\n| Migrate from tsup | Migration guide and compatibility notes | [guide-migrate-from-tsup](references/guide-migrate-from-tsup.md) |\n| Plugins | Rolldown, Rollup, Unplugin support | [advanced-plugins](references/advanced-plugins.md) |\n| Hooks | Lifecycle hooks for custom logic | [advanced-hooks](references/advanced-hooks.md) |\n| Programmatic API | Build from Node.js scripts, in-memory builds (`write: false`) | [advanced-programmatic](references/advanced-programmatic.md) |\n| Rolldown Options | Pass options directly to Rolldown | [advanced-rolldown-options](references/advanced-rolldown-options.md) |\n| CI Environment | CI detection, `'ci-only'` / `'local-only'` values | [advanced-ci](references/advanced-ci.md) |\n\n> For comprehensive migration assistance with complete option mappings, install the dedicated [`tsdown-migrate`](../tsdown-migrate/SKILL.md) skill: `npx skills add rolldown/tsdown --skill tsdown-migrate`\n\n## Build Options\n\n| Option | Usage | Reference |\n|--------|-------|-----------|\n| Entry points | `entry: ['src/*.ts', '!**/*.test.ts']` | [option-entry](references/option-entry.md) |\n| Output formats | `format: ['esm', 'cjs', 'iife', 'umd']` | [option-output-format](references/option-output-format.md) |\n| Output directory | `outDir: 'dist'`, `outExtensions` | [option-output-directory](references/option-output-directory.md) |\n| Type declarations | `dts: true`, `dts: { sourcemap, compilerOptions, vue }` | [option-dts](references/option-dts.md) |\n| Target environment | `target: 'es2020'`, `target: 'esnext'` | [option-target](references/option-target.md) |\n| Platform | `platform: 'node'`, `platform: 'browser'` | [option-platform](references/option-platform.md) |\n| Tree shaking | `treeshake: true`, custom options | [option-tree-shaking](references/option-tree-shaking.md) |\n| Minification | `minify: true`, `minify: 'dce-only'` | [option-minification](references/option-minification.md) |\n| Source maps | `sourcemap: true`, `'inline'`, `'hidden'` | [option-sourcemap](references/option-sourcemap.md) |\n| Watch mode | `watch: true`, watch options | [option-watch-mode](references/option-watch-mode.md) |\n| Cleaning | `clean: true`, clean patterns | [option-cleaning](references/option-cleaning.md) |\n| Log level | `logLevel: 'silent'`, `failOnWarn: false`, `suppressWarnings: [...]` | [option-log-level](references/option-log-level.md) |\n\n## Dependency Handling\n\n| Feature | Usage | Reference |\n|---------|-------|-----------|\n| Never bundle | `deps: { neverBundle: ['react', /^@myorg\\//] }` | [option-dependencies](references/option-dependencies.md) |\n| Always bundle | `deps: { alwaysBundle: ['dep-to-bundle'] }` | [option-dependencies](references/option-dependencies.md) |\n| Only bundle | `deps: { onlyBundle: ['cac', 'bumpp'] }` - Whitelist | [option-dependencies](references/option-dependencies.md) |\n| Only import | `deps: { onlyImport: ['cac'] }` - Whitelist runtime imports in output | [option-dependencies](references/option-dependencies.md) |\n| Externalize all | `deps: { neverBundle: true }` | [option-dependencies](references/option-dependencies.md) |\n| Resolve subpaths | `deps: { resolveDepSubpath: true }` - Resolve external subpath imports (default `false`) | [option-dependencies](references/option-dependencies.md) |\n| Auto external | Automatic dependency/peer/optional externalization | [option-dependencies](references/option-dependencies.md) |\n\n## Output Enhancement\n\n| Feature | Usage | Reference |\n|---------|-------|-----------|\n| Shims | `shims: true` - Add ESM/CJS compatibility | [option-shims](references/option-shims.md) |\n| CJS default | `cjsDefault: true` (default) / `false` | [option-cjs-default](references/option-cjs-default.md) |\n| Package exports | `exports: true` - Generate exports field | [option-package-exports](references/option-package-exports.md) |\n| CSS handling | **[experimental]** `css: { ... }` — full pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, code splitting; requires `@tsdown/css` | [option-css](references/option-css.md) |\n| CSS modules | `css: { modules: { localsConvention: 'camelCase' } }` — scoped class names for `.module.css` files | [option-css](references/option-css.md) |\n| CSS inject | `css: { inject: true }` — preserve CSS imports in JS output | [option-css](references/option-css.md) |\n| Copy files | `copy: 'public'` or `copy: { from, to, flatten, rename }` - Copy static assets to output | [option-copy](references/option-copy.md) |\n| Unbundle mode | `unbundle: true` - Preserve directory structure | [option-unbundle](references/option-unbundle.md) |\n| Root directory | `root: 'src'` - Control output directory mapping | [option-root](references/option-root.md) |\n| Executable | **[experimental]** `exe: true` - Bundle as standalone executable, cross-platform via `@tsdown/exe` | [option-exe](references/option-exe.md) |\n| Package validation | `publint: true`, `attw: true` - Validate package | [option-lint](references/option-lint.md) |\n\n## Framework & Runtime Support\n\n| Framework | Guide | Reference |\n|-----------|-------|-----------|\n| React | JSX transform, React Compiler | [recipe-react](references/recipe-react.md) |\n| Vue | SFC support, JSX | [recipe-vue](references/recipe-vue.md) |\n| Solid | SolidJS JSX transform | [recipe-solid](references/recipe-solid.md) |\n| Svelte | Svelte component libraries (source distribution recommended) | [recipe-svelte](references/recipe-svelte.md) |\n| WASM | WebAssembly modules via `rolldown-plugin-wasm` | [recipe-wasm](references/recipe-wasm.md) |\n\n## Common Patterns\n\n### Basic Library Bundle\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### Browser Library (IIFE/UMD)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n globalName: 'MyLib',\n platform: 'browser',\n minify: true,\n})\n```\n\n### React Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.tsx'],\n format: ['esm', 'cjs'],\n dts: true,\n deps: {\n neverBundle: ['react', 'react-dom'],\n },\n inputOptions: {\n jsx: { runtime: 'automatic' },\n },\n})\n```\n\n### Preserve Directory Structure\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n unbundle: true, // Preserve file structure\n format: ['esm'],\n dts: true,\n})\n```\n\n### CI-Aware Configuration\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n failOnWarn: 'ci-only', // opt-in: fail on warnings in CI\n publint: 'ci-only',\n attw: 'ci-only',\n})\n```\n\n### WASM Support\n\n```ts\nimport { wasm } from 'rolldown-plugin-wasm'\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [wasm()],\n})\n```\n\n### Library with CSS and Sass\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n target: 'chrome100',\n css: {\n preprocessorOptions: {\n scss: {\n additionalData: `@use \"src/styles/variables\" as *;`,\n },\n },\n },\n})\n```\n\n### Standalone Executable\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: true,\n})\n```\n\n### Cross-Platform Executable (requires `@tsdown/exe`)\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [\n { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },\n { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },\n { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },\n ],\n },\n})\n```\n\n### Advanced with Hooks\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n hooks: {\n 'build:before': async (context) => {\n console.log('Building...')\n },\n 'build:done': async (context) => {\n console.log('Build complete!')\n },\n },\n})\n```\n\n## Configuration Features\n\n### Multiple Configs\n\nExport an array for multiple build configurations:\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n },\n {\n entry: ['src/cli.ts'],\n format: ['esm'],\n platform: 'node',\n },\n])\n```\n\n### Conditional Config\n\nUse functions for dynamic configuration:\n\n```ts\nexport default defineConfig((options) => {\n const isDev = options.watch\n return {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n }\n})\n```\n\n### Workspace/Monorepo\n\nUse glob patterns to build multiple packages:\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n## CLI Quick Reference\n\n```bash\n# Basic commands\ntsdown # Build once\ntsdown --watch # Watch mode\ntsdown --config custom.ts # Custom config\nnpx tsdown-migrate # Migrate from tsup\n\n# Output options\ntsdown --format esm,cjs # Multiple formats\ntsdown -d lib # Custom output directory (--out-dir)\ntsdown --minify # Enable minification\ntsdown --dts # Generate declarations\ntsdown --exe # Bundle as standalone executable\ntsdown --unbundle # Bundleless mode\ntsdown --copy public # Copy static files to output\n\n# Entry options\ntsdown src/index.ts # Single entry\ntsdown src/*.ts # Glob patterns\ntsdown src/a.ts src/b.ts # Multiple entries\n\n# Workspace / Monorepo\ntsdown -W # Enable workspace mode\ntsdown -W -F my-package # Filter specific package\ntsdown --filter /^pkg-/ # Filter by regex\ntsdown -W --concurrency 4 # Limit parallel Rolldown builds\n\n# Development\ntsdown --watch # Watch mode\ntsdown --sourcemap # Generate source maps\ntsdown --clean # Clean output directory\ntsdown --from-vite # Reuse Vite config\ntsdown --tsconfig tsconfig.build.json # Custom tsconfig\n```\n\n## Best Practices\n\n1. **Always generate type declarations** for TypeScript libraries:\n ```ts\n { dts: true }\n ```\n\n2. **Externalize dependencies** to avoid bundling unnecessary code:\n ```ts\n { deps: { neverBundle: [/^react/, /^@myorg\\//] } }\n ```\n\n3. **Use tree shaking** for optimal bundle size:\n ```ts\n { treeshake: true }\n ```\n\n4. **Enable minification** for production builds:\n ```ts\n { minify: true }\n ```\n\n5. **Add shims** for better ESM/CJS compatibility:\n ```ts\n { shims: true } // Adds __dirname, __filename, etc.\n ```\n\n6. **Auto-generate package.json exports**:\n ```ts\n { exports: true } // Creates proper exports field\n ```\n\n7. **Use watch mode** during development:\n ```bash\n tsdown --watch\n ```\n\n8. **Preserve structure** for utilities with many files:\n ```ts\n { unbundle: true } // Keep directory structure\n ```\n\n9. **Validate packages** in CI before publishing:\n ```ts\n { publint: 'ci-only', attw: 'ci-only' }\n ```\n\n## Resources\n\n- Documentation: https://tsdown.dev\n- GitHub: https://github.com/rolldown/tsdown\n- Rolldown: https://rolldown.rs\n- Migration Guide: https://tsdown.dev/guide/migrate-from-tsup\n","frontmatter":{"name":"tsdown","description":"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."},"isInternal":false,"tokens":3599,"sizeBytes":13528},{"name":"README.md","path":"packages/rollup-plugin/README.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/packages/rollup-plugin/README.md","title":"rollup-plugin Documentation","category":"plugin-manifest","format":"markdown","content":"# [rollup-plugin-chrome-extension](https://www.extend-chrome.dev/rollup-plugin)\n\n[![npm (scoped)](https://img.shields.io/npm/v/rollup-plugin-chrome-extension.svg)](https://www.npmjs.com/package/rollup-plugin-chrome-extension)\n[![GitHub last commit](https://img.shields.io/github/last-commit/crxjs/rollup-plugin-chrome-extension.svg?logo=github)](https://github.com/crxjs/rollup-plugin-chrome-extension)\n![GitHub action badge](https://github.com/crxjs/rollup-plugin-chrome-extension/actions/workflows/rollup-plugin.yml/badge.svg)\n[![TypeScript Declarations Included](https://img.shields.io/badge/types-TypeScript-informational)](#typescript)\n\n\n \"rollup-plugin-chrome-extension\n\nThe bundler configuration for a Chrome Extension can be pretty complex.\n\nUse `manifest.json` as the input. Every file in the manifest will be bundled or\ncopied to the output folder.\n\nRPCE simplifies project config and supports many of Vite's features in the\nChrome Extension environment, including HMR.\n\n## [Documentation](https://www.extend-chrome.dev/rollup-plugin)\n\nWe have\n[v3 boilerplates](https://www.extend-chrome.dev/rollup-plugin#chrome-extension-boilerplates)\nfor [React JavaScript](https://github.com/crxjs/js-react-boilerplate),\n[React TypeScript](https://github.com/crxjs/ts-react-boilerplate) and\n[Svelte](https://github.com/kyrelldixon/svelte-tailwind-extension-boilerplate),\nas well as [instructions](https://www.extend-chrome.dev/rollup-plugin#usage) for\nsetting up your own project.\n\nSee the [documentation](https://www.extend-chrome.dev/rollup-plugin) for usage\nand how to get started.\n\n## Supporting\n\nIf these plugins have helped you ship your product faster, please consider\n[sponsoring me](https://github.com/sponsors/jacksteamdev) on GitHub.\n\n## Contributing\n\nWe encourage pull requests! This is a\n[pnpm monorepo](https://pnpm.io/workspaces), so use pnpm instead of Yarn or npm.\n","isInternal":false,"tokens":509,"sizeBytes":2030},{"name":"README.md","path":"packages/vite-plugin/README.md","rawUrl":"https://raw.githubusercontent.com/crxjs/chrome-extension-tools/HEAD/packages/vite-plugin/README.md","title":"vite-plugin Documentation","category":"plugin-manifest","format":"markdown","content":"![CRXJS](./banner-github.png)\n\n

CRXJS

\n\n

\nModern Chrome extension development with built-in HMR and zero-config setup\n

\n\n

\n\n\"NPM\n\n

\n\n

\n📚 Documentation |\n💬 Discord \n

\n\n\n## 📦 Create CRXJS Project\n```shell\nnpm create crxjs@latest\n``` \n\n> [!IMPORTANT]\n> `@latest` MUST NOT be omitted, otherwise `npm` may resolve to a cached and outdated version of the package.\n\n## ✨ Features\n\n- 🧩 **Full Vite Plugin Ecosystem** - Leverage any Vite-compatible plugins with zero extra setup \n- ⚙️ **Zero Configuration** - Start developing immediately with intelligent defaults \n- 3️⃣ **Manifest V3 Support** - Built for modern Chrome extensions with enhanced security \n- 🔥 **True Hot Module Replacement** - Instant UI updates while preserving extension state 🎈**works with content scripts**\n- 📁 **Static Asset Import** - Directly reference images/fonts in your code\n- 🤖 **Auto Web-Accessible Resources** - Automatic generation of `web_accessible_resources` manifest entries \n\n> [!NOTE] \n> Looking for MV2 support? See [`rollup-plugin`](packages/rollup-plugin/README.md) \n\n## 💻 Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for local development workflows.\n\n## 💝 Contributors\n\nThis project exists thanks to all the people who contribute.\n\nAnd thank you to all our backers! 🙏\n\n\n \n\n\n## 🤝 Supporting\n\nIf these plugins have helped you ship your product faster, please consider\n[sponsoring me](https://github.com/sponsors/jacksteamdev) on GitHub.\n","isInternal":false,"tokens":545,"sizeBytes":2018}],"systemPromptSnippet":"\n\n# tsdown Skills\n\nAgent skills that help AI coding agents understand and work with [tsdown](https://tsdown.dev), the elegant library bundler.\n\n## Installation\n\n```bash\nnpx skills add rolldown/tsdown\n```\n\nThis will install all tsdown skills (including the migration skill). To install only the tsdown skill:\n\n```bash\nnpx skills add rolldown/tsdown --skill tsdown\n```\n\n## What's Included\n\nThe tsdown skill provides Claude Code with knowledge about:\n\n- **Core Concepts** - What tsdown is, why use it, key features\n- **Configuration** - Config file formats, options, multiple configs, workspace support\n- **Build Options** - Entry points, output formats, type declarations, targets\n- **Dependency Handling** - External/inline dependencies, auto-externalization\n- **Output Enhancement** - Shims, CJS defaults, package exports\n- **Framework Support** - React, Vue, Solid, Svelte integration\n- **Advanced Features** - Plugins, hooks, programmatic API, Rolldown options\n- **CLI Commands** - All CLI options and usage patterns\n- **Migration** - Migrating from tsup to tsdown\n\n## Usage\n\nOnce installed, Claude Code will automatically use tsdown knowledge when:\n\n- Building TypeScript/JavaScript libraries\n- Configuring bundlers for library projects\n- Setting up type declaration generation\n- Working with multi-format builds (ESM, CJS, IIFE, UMD)\n- Migrating from tsup\n- Building framework component libraries\n\n### Example Prompts\n\n```\nSet up tsdown to build my TypeScript library with ESM and CJS formats\n```\n\n```\nConfigure tsdown to generate type declarations and bundle for browsers\n```\n\n```\nAdd React support to my tsdown config with Fast Refresh\n```\n\n```\nHelp me migrate from tsup to tsdown\n```\n\n```\nSet up a monorepo build with tsdown workspace support\n```\n\n## Related Skills\n\n- **[tsdown-migrate](https://github.com/rolldown/tsdown/tree/main/skills/tsdown-migrate)** - Dedicated skill for migrating from tsup to tsdown, with complete option mappings, config transformations, and troubleshooting guidance.\n\n## Documentation\n\n- [tsdown Documentation](https://tsdown.dev)\n- [GitHub Repository](https://github.com/rolldown/tsdown)\n- [Rolldown](https://rolldown.rs)\n- [Migration Guide](https://tsdown.dev/guide/migrate-from-tsup)\n\n## License\n\nMIT\n\n\n# Benchmark\n\ntsdown delivers exceptional performance:\n\n- **~2x faster** than tsup for standard builds\n- **Up to 8x faster** for TypeScript declaration generation\n\nFor detailed comparisons, see [bundler-benchmark](https://gugustinette.github.io/bundler-benchmark/).\n\n\n# CI Environment Support\n\nAutomatically detect CI environments and toggle features based on local vs CI builds.\n\n## Overview\n\ntsdown detects CI from the `CI` environment variable. CI mode is enabled when `process.env.CI` is set to a value other than `0` or `false` (case-insensitive).\n\n## CI-Aware Values\n\nSeveral options accept CI-aware string values:\n\n| Value | Behavior |\n|-------|----------|\n| `true` | Always enabled |\n| `false` | Always disabled |\n| `'ci-only'` | Enabled only in CI, disabled locally |\n| `'local-only'` | Enabled only locally, disabled in CI |\n\n## Supported Options\n\nThese options accept CI-aware values:\n\n- `dts` - TypeScript declaration file generation\n- `publint` - Package lint validation\n- `attw` - \"Are the types wrong\" validation\n- `report` - Bundle size reporting\n- `exports` - Auto-generate `package.json` exports\n- `unused` - Unused dependency check\n- `devtools` - DevTools integration\n- `failOnWarn` - Fail on warnings (defaults to `false`)\n\n## Usage\n\n### String Form\n\n```ts\nexport default defineConfig({\n dts: 'local-only', // Skip DTS in CI for faster builds\n publint: 'ci-only', // Only run publint in CI\n failOnWarn: 'ci-only', // Fail on warnings in CI only (opt-in)\n})\n```\n\n### Object Form\n\nWhen an option takes a configuration object, set `enabled` to a CI-aware value:\n\n```ts\nexport default defineConfig({\n publint: {\n enabled: 'ci-only',\n level: 'error',\n },\n attw: {\n enabled: 'ci-only',\n profile: 'node16',\n },\n})\n```\n\n### Config Function\n\nThe config function receives a `ci` boolean in its context:\n\n```ts\nexport default defineConfig((_, { ci }) => ({\n minify: ci,\n sourcemap: !ci,\n}))\n```\n\n## Typical CI Configuration\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n dts: true,\n failOnWarn: 'ci-only',\n publint: 'ci-only',\n attw: 'ci-only',\n})\n```\n\n## Related Options\n\n- [Package Validation](option-lint.md) - publint and attw configuration\n- [Log Level](option-log-level.md) - `failOnWarn` option details\n\n\n# Lifecycle Hooks\n\nExtend the build process with lifecycle hooks.\n\n## Overview\n\nHooks provide a way to inject custom logic at specific stages of the build lifecycle. Inspired by [unbuild](https://github.com/unjs/unbuild).\n\n**Recommendation:** Use [plugins](advanced-plugins.md) for most extensions. Use hooks for simple custom tasks or Rolldown plugin injection.\n\n## Usage Patterns\n\n### Object Syntax\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n hooks: {\n 'build:prepare': async (context) => {\n console.log('Build starting...')\n },\n 'build:done': async (context) => {\n console.log('Build complete!')\n },\n },\n})\n```\n\n### Function Syntax\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n hooks(hooks) {\n hooks.hook('build:prepare', () => {\n console.log('Preparing build...')\n })\n\n hooks.hook('build:before', (context) => {\n console.log(`Building format: ${context.format}`)\n })\n },\n})\n```\n\n## Available Hooks\n\n### `build:prepare`\n\nCalled before the build process starts.\n\n**When:** Once per build session\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Setup tasks\n- Validation\n- Environment preparation\n\n**Example:**\n```ts\nhooks: {\n 'build:prepare': async (context) => {\n console.log('Starting build for:', context.options.entry)\n await cleanOldFiles()\n },\n}\n```\n\n### `build:before`\n\nCalled before each Rolldown build.\n\n**When:** Once per format (ESM, CJS, etc.)\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n buildOptions: BuildOptions,\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Modify build options per format\n- Inject plugins dynamically\n- Format-specific setup\n\n**Example:**\n```ts\nhooks: {\n 'build:before': async (context) => {\n console.log(`Building ${context.buildOptions.format} format...`)\n\n // Add format-specific plugin\n if (context.buildOptions.format === 'iife') {\n context.buildOptions.plugins.push(browserPlugin())\n }\n },\n}\n```\n\n### `build:done`\n\nCalled after the build completes.\n\n**When:** Once per build session\n\n**Context:**\n```ts\n{\n options: ResolvedConfig,\n chunks: RolldownChunk[],\n hooks: Hookable\n}\n```\n\n**Use cases:**\n- Post-processing\n- Asset copying\n- Notifications\n- Deployment\n\n**Example:**\n```ts\nhooks: {\n 'build:done': async (context) => {\n console.log(`Built ${context.chunks.length} chunks`)\n\n // Copy additional files\n await copyAssets()\n\n // Send notification\n notifyBuildComplete()\n },\n}\n```\n\n## Common Patterns\n\n### Build Notifications\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': () => {\n console.log('🚀 Starting build...')\n },\n 'build:done': (context) => {\n const size = context.chunks.reduce((sum, c) => sum + c.code.length, 0)\n console.log(`✅ Build complete! Total size: ${size} bytes`)\n },\n },\n})\n```\n\n### Conditional Plugin Injection\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n hooks.hook('build:before', (context) => {\n // Add minification only for production\n if (process.env.NODE_ENV === 'production') {\n context.buildOptions.plugins.push(minifyPlugin())\n }\n })\n },\n})\n```\n\n### Custom File Copy\n\n```ts\nimport { copyFile } from 'fs/promises'\n\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n // Copy README to dist\n await copyFile('README.md', `${context.options.outDir}/README.md`)\n },\n },\n})\n```\n\n### Build Metrics\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': (context) => {\n context.startTime = Date.now()\n },\n 'build:done': (context) => {\n const duration = Date.now() - context.startTime\n console.log(`Build took ${duration}ms`)\n\n // Log chunk sizes\n context.chunks.forEach((chunk) => {\n console.log(`${chunk.fileName}: ${chunk.code.length} bytes`)\n })\n },\n },\n})\n```\n\n### Format-Specific Logic\n\n```ts\nexport default defineConfig({\n format: ['esm', 'cjs', 'iife'],\n hooks: {\n 'build:before': (context) => {\n const format = context.buildOptions.format\n\n if (format === 'iife') {\n // Browser-specific setup\n context.buildOptions.globalName = 'MyLib'\n } else if (format === 'cjs') {\n // Node-specific setup\n context.buildOptions.platform = 'node'\n }\n },\n },\n})\n```\n\n### Deployment Hook\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n if (process.env.DEPLOY === 'true') {\n console.log('Deploying to CDN...')\n await deployToCDN(context.options.outDir)\n }\n },\n },\n})\n```\n\n## Advanced Usage\n\n### Multiple Hooks\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n // Register multiple hooks\n hooks.hook('build:prepare', setupEnvironment)\n hooks.hook('build:prepare', validateConfig)\n\n hooks.hook('build:before', injectPlugins)\n hooks.hook('build:before', logFormat)\n\n hooks.hook('build:done', generateManifest)\n hooks.hook('build:done', notifyComplete)\n },\n})\n```\n\n### Async Hooks\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:prepare': async (context) => {\n await fetchRemoteConfig()\n await initializeDatabase()\n },\n 'build:done': async (context) => {\n await uploadToS3(context.chunks)\n await invalidateCDN()\n },\n },\n})\n```\n\n### Error Handling\n\n```ts\nexport default defineConfig({\n hooks: {\n 'build:done': async (context) => {\n try {\n await riskyOperation()\n } catch (error) {\n console.error('Hook failed:', error)\n // Don't throw - allow build to complete\n }\n },\n },\n})\n```\n\n## Hookable API\n\ntsdown uses [hookable](https://github.com/unjs/hookable) for hooks. Additional methods:\n\n```ts\nexport default defineConfig({\n hooks(hooks) {\n // Register hook\n hooks.hook('build:done', handler)\n\n // Register hook once\n hooks.hookOnce('build:prepare', handler)\n\n // Remove hook\n hooks.removeHook('build:done', handler)\n\n // Clear all hooks for event\n hooks.removeHooks('build:done')\n\n // Call hooks manually\n await hooks.callHook('build:done', context)\n },\n})\n```\n\n## Tips\n\n1. **Use plugins** for most extensions\n2. **Hooks for simple tasks** like notifications or file copying\n3. **Async hooks supported** for I/O operations\n4. **Don't throw errors** unless you want to fail the build\n5. **Context is mutable** in `build:before` for advanced use cases\n6. **Multiple hooks allowed** for the same event\n\n## Troubleshooting\n\n### Hook Not Called\n\n- Verify hook name is correct\n- Check hook is registered in config\n- Ensure async hooks are awaited\n\n### Build Fails in Hook\n\n- Add try/catch for error handling\n- Don't throw unless intentional\n- Log errors for debugging\n\n### Context Undefined\n\n- Check which hook you're using\n- Verify context properties available for that hook\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Rolldown Options](advanced-rolldown-options.md) - Build options\n- [Watch Mode](option-watch-mode.md) - Development workflow\n\n\n# Plugins\n\nExtend tsdown with plugins from multiple ecosystems.\n\n## Overview\n\ntsdown, built on Rolldown, supports plugins from multiple ecosystems to extend and customize the bundling process.\n\n## Supported Ecosystems\n\n### 1. Rolldown Plugins\n\nNative plugins designed for Rolldown:\n\n```ts\nimport RolldownPlugin from 'rolldown-plugin-something'\n\nexport default defineConfig({\n plugins: [RolldownPlugin()],\n})\n```\n\n**Compatibility:** ✅ Full support\n\n### 2. Unplugin\n\nUniversal plugins that work across bundlers:\n\n```ts\nimport UnpluginPlugin from 'unplugin-something'\n\nexport default defineConfig({\n plugins: [UnpluginPlugin.rolldown()],\n})\n```\n\n**Compatibility:** ✅ Most unplugin-* plugins work\n\n**Examples:**\n- `unplugin-vue-components`\n- `unplugin-auto-import`\n- `unplugin-icons`\n\n### 3. Rollup Plugins\n\nMost Rollup plugins work with tsdown:\n\n```ts\nimport RollupPlugin from '@rollup/plugin-something'\n\nexport default defineConfig({\n plugins: [RollupPlugin()],\n})\n```\n\n**Compatibility:** ✅ High compatibility\n\n**Type Issues:** May cause TypeScript errors - use type casting:\n\n```ts\nimport RollupPlugin from 'rollup-plugin-something'\n\nexport default defineConfig({\n plugins: [\n // @ts-expect-error Rollup plugin type mismatch\n RollupPlugin(),\n // Or cast to any\n RollupPlugin() as any,\n ],\n})\n```\n\n### 4. Vite Plugins\n\nSome Vite plugins may work:\n\n```ts\nimport VitePlugin from 'vite-plugin-something'\n\nexport default defineConfig({\n plugins: [\n // @ts-expect-error Vite plugin type mismatch\n VitePlugin(),\n ],\n})\n```\n\n**Compatibility:** ⚠️ Limited - only if not using Vite-specific APIs\n\n**Note:** Improved support planned for future releases.\n\n## Usage\n\n### Basic Plugin Usage\n\n```ts\nimport { defineConfig } from 'tsdown'\nimport SomePlugin from 'some-plugin'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [SomePlugin()],\n})\n```\n\n### Multiple Plugins\n\n```ts\nimport PluginA from 'plugin-a'\nimport PluginB from 'plugin-b'\nimport PluginC from 'plugin-c'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n PluginA(),\n PluginB({ option: true }),\n PluginC(),\n ],\n})\n```\n\n### Conditional Plugins\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n plugins: [\n SomePlugin(),\n options.watch && DevPlugin(),\n !options.watch && ProdPlugin(),\n ].filter(Boolean),\n}))\n```\n\n## Common Plugin Patterns\n\n### JSON Import\n\n```ts\nimport json from '@rollup/plugin-json'\n\nexport default defineConfig({\n plugins: [json()],\n})\n```\n\n### Node Resolve\n\n```ts\nimport { nodeResolve } from '@rollup/plugin-node-resolve'\n\nexport default defineConfig({\n plugins: [nodeResolve()],\n})\n```\n\n### CommonJS\n\n```ts\nimport commonjs from '@rollup/plugin-commonjs'\n\nexport default defineConfig({\n plugins: [commonjs()],\n})\n```\n\n### Replace\n\n```ts\nimport replace from '@rollup/plugin-replace'\n\nexport default defineConfig({\n plugins: [\n replace({\n 'process.env.NODE_ENV': JSON.stringify('production'),\n __VERSION__: JSON.stringify('1.0.0'),\n }),\n ],\n})\n```\n\n### Auto Import\n\n```ts\nimport AutoImport from 'unplugin-auto-import/rolldown'\n\nexport default defineConfig({\n plugins: [\n AutoImport({\n imports: ['vue', 'vue-router'],\n dts: 'src/auto-imports.d.ts',\n }),\n ],\n})\n```\n\n### Vue Components\n\n```ts\nimport Components from 'unplugin-vue-components/rolldown'\n\nexport default defineConfig({\n plugins: [\n Components({\n dts: 'src/components.d.ts',\n }),\n ],\n})\n```\n\n## Framework-Specific Plugins\n\n### React\n\n```ts\nimport react from '@vitejs/plugin-react'\n\nexport default defineConfig({\n entry: ['src/index.tsx'],\n plugins: [\n // @ts-expect-error Vite plugin\n react(),\n ],\n})\n```\n\n### Vue\n\n```ts\nimport vue from '@vitejs/plugin-vue'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n // @ts-expect-error Vite plugin\n vue(),\n ],\n})\n```\n\n### Solid\n\n```ts\nimport solid from 'vite-plugin-solid'\n\nexport default defineConfig({\n entry: ['src/index.tsx'],\n plugins: [\n // @ts-expect-error Vite plugin\n solid(),\n ],\n})\n```\n\n### Svelte\n\n```ts\nimport { svelte } from '@sveltejs/vite-plugin-svelte'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [\n // @ts-expect-error Vite plugin\n svelte(),\n ],\n})\n```\n\n## Writing Custom Plugins\n\nFollow Rolldown's plugin development guide:\n\n### Basic Plugin Structure\n\n```ts\nimport type { Plugin } from 'rolldown'\n\nfunction myPlugin(): Plugin {\n return {\n name: 'my-plugin',\n\n // Transform hook\n transform(code, id) {\n if (id.endsWith('.custom')) {\n return {\n code: transformCode(code),\n map: null,\n }\n }\n },\n\n // Other hooks...\n }\n}\n```\n\n### Using Custom Plugin\n\n```ts\nimport { myPlugin } from './my-plugin'\n\nexport default defineConfig({\n plugins: [myPlugin()],\n})\n```\n\n## Plugin Configuration\n\n### Plugin-Specific Options\n\nRefer to each plugin's documentation for configuration options.\n\n### Plugin Order\n\nPlugins run in the order they're defined:\n\n```ts\nexport default defineConfig({\n plugins: [\n PluginA(), // Runs first\n PluginB(), // Runs second\n PluginC(), // Runs last\n ],\n})\n```\n\n## Troubleshooting\n\n### Type Errors with Rollup/Vite Plugins\n\nUse type casting:\n\n```ts\nplugins: [\n // Option 1: @ts-expect-error\n // @ts-expect-error Plugin type mismatch\n SomePlugin(),\n\n // Option 2: as any\n SomePlugin() as any,\n]\n```\n\n### Plugin Not Working\n\n1. **Check compatibility** - Verify plugin supports your bundler\n2. **Read documentation** - Follow plugin's setup instructions\n3. **Check plugin order** - Some plugins depend on execution order\n4. **Enable debug mode** - Use `--debug` flag\n\n### Vite Plugin Fails\n\nVite plugins may rely on Vite-specific APIs:\n\n1. **Find Rollup equivalent** - Look for Rollup version of plugin\n2. **Use Unplugin version** - Check for `unplugin-*` alternative\n3. **Wait for support** - Vite plugin support improving\n\n## Resources\n\n- [Rolldown Plugin Development](https://rolldown.rs/apis/plugin-api)\n- [Unplugin Documentation](https://unplugin.unjs.io/)\n- [Rollup Plugins](https://github.com/rollup/plugins)\n- [Vite Plugins](https://vitejs.dev/plugins/)\n\n## Tips\n\n1. **Prefer Rolldown plugins** for best compatibility\n2. **Use Unplugin** for cross-bundler support\n3. **Cast types** for Rollup/Vite plugins\n4. **Test thoroughly** when using cross-ecosystem plugins\n5. **Check plugin docs** for specific configuration\n6. **Write custom plugins** for unique needs\n\n## Related\n\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [Rolldown Options](advanced-rolldown-options.md) - Advanced Rolldown config\n- [React Recipe](recipe-react.md) - React setup with plugins\n- [Vue Recipe](recipe-vue.md) - Vue setup with plugins\n\n\n# Programmatic Usage\n\nUse tsdown from JavaScript/TypeScript code.\n\n## Overview\n\ntsdown can be imported and used programmatically in your Node.js scripts, custom build tools, or automation workflows.\n\n## Basic Usage\n\n### Simple Build\n\n```ts\nimport { build } from 'tsdown'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### With Options\n\n```ts\nimport { build } from 'tsdown'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n dts: true,\n minify: true,\n sourcemap: true,\n clean: true,\n})\n```\n\n### In-Memory Output\n\nSet `write: false` to access generated chunks and assets without writing the\nbundle output to disk:\n\n```ts\nimport { build } from 'tsdown'\n\nconst bundles = await build({\n entry: ['src/index.ts'],\n format: 'esm',\n write: false,\n clean: false,\n})\n\nfor (const bundle of bundles) {\n for (const output of bundle.chunks) {\n const contents = output.type === 'chunk' ? output.code : output.source\n console.log(output.fileName, contents)\n }\n}\n```\n\n`build()` currently returns a `TsdownBundle[]`, with one bundle for each\nresolved configuration. Even a single configuration returns an array; its\nin-memory Rolldown outputs are available in `bundle.chunks`.\n\nThe `write` option controls Rolldown's bundle output, while other file operations\nare configured separately. For example, `clean` defaults to `true`, so set\n`clean: false` as above if existing output directories must remain untouched.\nExplicitly enabled features such as `copy` or `exports` may still write files.\n`write: false` is incompatible with watch mode.\n\n## API Reference\n\n### build()\n\nMain function to run a build.\n\n```ts\nimport { build } from 'tsdown'\n\nawait build(options)\n```\n\n**Parameters:**\n- `options` - Build configuration object (same as config file)\n\n**Returns:**\n- `Promise` - One bundle for each resolved configuration\n\n**Throws:**\n- Build errors if compilation fails\n\n## Configuration Object\n\nAll config file options are available:\n\n```ts\nimport { build, defineConfig } from 'tsdown'\n\nconst config = defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: true,\n sourcemap: true,\n deps: {\n neverBundle: ['react', 'react-dom'],\n },\n plugins: [/* plugins */],\n hooks: {\n 'build:done': async () => {\n console.log('Build complete!')\n },\n },\n})\n\nawait build(config)\n```\n\nSee [Config Reference](option-config-file.md) for all options.\n\n## Common Patterns\n\n### Custom Build Script\n\n```ts\n// scripts/build.ts\nimport { build } from 'tsdown'\n\nasync function main() {\n console.log('Building library...')\n\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n })\n\n console.log('Build complete!')\n}\n\nmain().catch(console.error)\n```\n\nRun with:\n```bash\ntsx scripts/build.ts\n```\n\n### Multiple Builds\n\n```ts\nimport { build } from 'tsdown'\n\n// Build main library\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n dts: true,\n})\n\n// Build CLI tool\nawait build({\n entry: ['src/cli.ts'],\n format: ['esm'],\n outDir: 'dist/bin',\n platform: 'node',\n shims: true,\n})\n```\n\n### Conditional Build\n\n```ts\nimport { build } from 'tsdown'\n\nconst isDev = process.env.NODE_ENV === 'development'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n clean: !isDev,\n})\n```\n\n### With Error Handling\n\n```ts\nimport { build } from 'tsdown'\n\ntry {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n })\n console.log('✅ Build successful')\n} catch (error) {\n console.error('❌ Build failed:', error)\n process.exit(1)\n}\n```\n\n### Automated Workflow\n\n```ts\nimport { build } from 'tsdown'\nimport { execSync } from 'child_process'\n\nasync function release() {\n // Clean\n console.log('Cleaning...')\n execSync('rm -rf dist')\n\n // Build\n console.log('Building...')\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: true,\n })\n\n // Test\n console.log('Testing...')\n execSync('npm test')\n\n // Publish\n console.log('Publishing...')\n execSync('npm publish')\n}\n\nrelease().catch(console.error)\n```\n\n### Build with Post-Processing\n\n```ts\nimport { build } from 'tsdown'\nimport { copyFileSync } from 'fs'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n hooks: {\n 'build:done': async () => {\n // Copy additional files\n copyFileSync('README.md', 'dist/README.md')\n copyFileSync('LICENSE', 'dist/LICENSE')\n console.log('Copied additional files')\n },\n },\n})\n```\n\n## Watch Mode\n\nUnfortunately, watch mode is not directly exposed in the programmatic API. Use the CLI for watch mode:\n\n```ts\n// Use CLI for watch mode\nimport { spawn } from 'child_process'\n\nspawn('tsdown', ['--watch'], {\n stdio: 'inherit',\n shell: true,\n})\n```\n\n## Integration Examples\n\n### With Task Runner\n\n```ts\n// gulpfile.js\nimport { build } from 'tsdown'\nimport gulp from 'gulp'\n\ngulp.task('build', async () => {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n })\n})\n\ngulp.task('watch', () => {\n return gulp.watch('src/**/*.ts', gulp.series('build'))\n})\n```\n\n### With Custom CLI\n\n```ts\n// scripts/cli.ts\nimport { build } from 'tsdown'\nimport { Command } from 'commander'\n\nconst program = new Command()\n\nprogram\n .command('build')\n .option('--prod', 'Production build')\n .action(async (options) => {\n await build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: options.prod,\n sourcemap: !options.prod,\n })\n })\n\nprogram.parse()\n```\n\n### With CI/CD\n\n```ts\n// .github/scripts/build.ts\nimport { build } from 'tsdown'\n\nconst isCI = process.env.CI === 'true'\n\nawait build({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n minify: isCI,\n clean: true,\n})\n\n// Upload to artifact storage\nif (isCI) {\n // Upload dist/ to S3, etc.\n}\n```\n\n## TypeScript Support\n\n```ts\n// scripts/build.ts\nimport { build, type UserConfig } from 'tsdown'\n\nconst config: UserConfig = {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n}\n\nawait build(config)\n```\n\n## Tips\n\n1. **Use TypeScript** for type safety\n2. **Handle errors** properly\n3. **Use hooks** for custom logic\n4. **Log progress** for visibility\n5. **Use CLI for watch** mode\n6. **Exit on error** in scripts\n\n## Troubleshooting\n\n### Import Errors\n\nEnsure tsdown is installed:\n```bash\npnpm add -D tsdown\n```\n\n### Type Errors\n\nImport types:\n```ts\nimport type { UserConfig } from 'tsdown'\n```\n\n### Build Fails Silently\n\nAdd error handling:\n```ts\ntry {\n await build(config)\n} catch (error) {\n console.error(error)\n process.exit(1)\n}\n```\n\n### Options Not Working\n\nCheck spelling and types:\n```ts\n// ✅ Correct\n{ format: ['esm', 'cjs'] }\n\n// ❌ Wrong\n{ formats: ['esm', 'cjs'] }\n```\n\n## Related\n\n- [Config File](option-config-file.md) - Configuration options\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [CLI](reference-cli.md) - Command-line interface\n- [Plugins](advanced-plugins.md) - Plugin system\n\n\n# Customizing Rolldown Options\n\nPass options directly to the underlying Rolldown bundler.\n\n## Overview\n\ntsdown uses [Rolldown](https://rolldown.rs) as its core bundling engine. You can override Rolldown's input and output options directly for fine-grained control.\n\n**Warning:** You should be familiar with Rolldown's behavior before overriding options. Refer to the [Rolldown Config Options](https://rolldown.rs/reference/InputOptions.input) documentation.\n\n## Input Options\n\n### Using an Object\n\n```ts\nexport default defineConfig({\n inputOptions: {\n cwd: './custom-directory',\n },\n})\n```\n\n### Using a Function\n\nDynamically modify options based on the output format:\n\n```ts\nexport default defineConfig({\n inputOptions(inputOptions, format) {\n inputOptions.cwd = './custom-directory'\n return inputOptions\n },\n})\n```\n\n## Output Options\n\n### Using an Object\n\n```ts\nexport default defineConfig({\n outputOptions: {\n legalComments: 'inline',\n },\n})\n```\n\n### Using a Function\n\n```ts\nexport default defineConfig({\n outputOptions(outputOptions, format) {\n if (format === 'esm') {\n outputOptions.legalComments = 'inline'\n }\n return outputOptions\n },\n})\n```\n\n## Common Use Cases\n\n### Preserve Legal Comments\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outputOptions: {\n legalComments: 'inline',\n },\n})\n```\n\n### Custom Working Directory\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n inputOptions: {\n cwd: './packages/my-lib',\n },\n})\n```\n\n### Format-Specific Options\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outputOptions(outputOptions, format) {\n if (format === 'esm') {\n outputOptions.legalComments = 'inline'\n }\n return outputOptions\n },\n})\n```\n\n## When to Use\n\n- When tsdown doesn't expose a specific Rolldown option\n- For format-specific Rolldown customizations\n- For advanced bundling scenarios\n\n## Tips\n\n1. **Read Rolldown docs** before overriding options\n2. **Use functions** for format-specific customization\n3. **Test thoroughly** when overriding defaults\n4. **Prefer tsdown options** when available (e.g., use `minify` instead of setting it via `outputOptions`)\n\n## Related\n\n- [Plugins](advanced-plugins.md) - Plugin system\n- [Hooks](advanced-hooks.md) - Lifecycle hooks\n- [Config File](option-config-file.md) - Configuration options\n\n\n# Getting Started\n\nQuick guide to installing and using tsdown for the first time.\n\n## Installation\n\nInstall tsdown as a development dependency:\n\n```bash\npnpm add -D tsdown\n\n# Optionally install TypeScript if not using isolatedDeclarations\npnpm add -D typescript\n```\n\n**Requirements:**\n- Node.js 22.18.0 or higher **to run tsdown** (build-time only)\n- Experimental support for Deno and Bun\n\n> [!NOTE]\n> The Node.js 22.18+ requirement only applies to the environment that runs `tsdown` itself. The **bundled output** can target much lower Node.js versions via the [`target`](./option-target.md) option, so libraries built with tsdown are not locked to Node.js 22+ at runtime.\n>\n> If your package needs to support Node.js 18 / 20, the recommended workflow is to **build with Node.js 22+ in CI**, then **test the built output (or the packed tarball) against the lower Node.js versions** you intend to support.\n\n## Quick Start Templates\n\nUse `create-tsdown` CLI for instant setup:\n\n```bash\npnpm create tsdown@latest\n```\n\nProvides templates for:\n- Pure TypeScript libraries\n- React component libraries\n- Vue component libraries\n- Ready-to-use configurations\n\n## First Bundle\n\n### 1. Create Source Files\n\n```ts\n// src/index.ts\nimport { hello } from './hello.ts'\nhello()\n\n// src/hello.ts\nexport function hello() {\n console.log('Hello tsdown!')\n}\n```\n\n### 2. Create Config File\n\n```ts\n// tsdown.config.ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['./src/index.ts'],\n})\n```\n\n### 3. Run Build\n\n```bash\n./node_modules/.bin/tsdown\n```\n\nOutput: `dist/index.mjs`\n\n### 4. Test Output\n\n```bash\nnode dist/index.mjs\n# Output: Hello tsdown!\n```\n\n## Add to npm Scripts\n\n```json\n{\n \"scripts\": {\n \"build\": \"tsdown\"\n }\n}\n```\n\nRun with:\n\n```bash\npnpm build\n```\n\n## CLI Commands\n\n```bash\n# Check version\ntsdown --version\n\n# View help\ntsdown --help\n\n# Build with watch mode\ntsdown --watch\n\n# Build with specific format\ntsdown --format esm,cjs\n\n# Generate type declarations\ntsdown --dts\n```\n\n## Basic Configurations\n\n### TypeScript Library (ESM + CJS)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### Browser Library (IIFE)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n globalName: 'MyLib',\n platform: 'browser',\n minify: true,\n})\n```\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n## Using Plugins\n\nAdd Rolldown, Rollup, or Unplugin plugins:\n\n```ts\nimport SomePlugin from 'some-plugin'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n plugins: [SomePlugin()],\n})\n```\n\n## Watch Mode\n\nEnable automatic rebuilds on file changes:\n\n```bash\ntsdown --watch\n# or\ntsdown -w\n```\n\n## Next Steps\n\n- Configure [entry points](option-entry.md) with glob patterns\n- Set up [multiple output formats](option-output-format.md)\n- Enable [type declaration generation](option-dts.md)\n- Explore [plugins](advanced-plugins.md) for extended functionality\n- Read [migration guide](guide-migrate-from-tsup.md) if coming from tsup\n\n\n# Introduction\n\n**tsdown** is _The Elegant Library Bundler_ — a fast, simple bundler for TypeScript and JavaScript libraries powered by Rolldown (Rust-based).\n\n## Why tsdown?\n\nBuilt on [Rolldown](https://rolldown.rs), tsdown provides a complete out-of-the-box solution for library authors:\n\n- **Simplified Configuration**: Sensible defaults for library development, minimal boilerplate\n- **Library-Specific Features**: Auto TypeScript declarations, multiple output formats, package validation\n- **Future-Ready**: Official Rolldown project, foundation for Rolldown Vite's Library Mode\n\n## Plugin Ecosystem\n\nSupports the full Rolldown plugin ecosystem plus most Rollup plugins. See [Plugins](advanced-plugins.md).\n\n## What Can It Bundle?\n\n- **TypeScript/JavaScript**: `.ts`, `.js` with modern syntax\n- **TypeScript Declarations**: Auto-generate `.d.ts` files\n- **Multiple Formats**: `esm`, `cjs`, `iife`, `umd`\n- **Assets**: `.json`, `.wasm`, CSS files\n- Built-in tree shaking, minification, and source maps\n\n## Key Differences from Rolldown\n\ntsdown wraps Rolldown with library-specific features:\n- Auto-external `dependencies`, `peerDependencies`, and `optionalDependencies` from `package.json`\n- DTS generation\n- `package.json` exports field generation\n- Watch mode with keyboard shortcuts\n- CSS preprocessing pipeline\n- Executable bundling (SEA)\n\n## Prior Arts\n\nInspired by: Rollup, esbuild, tsup, unbuild. Powered by Rolldown.\n\n## Related\n\n- [Getting Started](guide-getting-started.md) - Installation and first build\n- [Migrate from tsup](guide-migrate-from-tsup.md) - Migration guide\n\n\n# Migrate from tsup\n\nMigration guide for switching from tsup to tsdown.\n\n## Overview\n\ntsdown is built on Rolldown (Rust-based) vs tsup's esbuild, providing faster and more powerful bundling while maintaining compatibility.\n\n## Automatic Migration\n\n### Single Package\n\n```bash\nnpx tsdown-migrate\n```\n\n### Monorepo\n\n```bash\n# Using glob patterns\nnpx tsdown-migrate packages/*\n\n# Multiple directories\nnpx tsdown-migrate packages/foo packages/bar\n```\n\n### Migration Options\n\n- `[...dirs]` - Directories to migrate (supports globs)\n- `--dry-run` or `-d` - Preview changes without modifying files\n- `--yes` or `-y` - Skip confirmation (required in non-interactive environments)\n- `--package-manager ` - Override package manager auto-detection\n- `--no-install` - Skip dependency installation\n\nFor non-interactive callers that install dependencies separately:\n\n```bash\nnpx tsdown-migrate --yes --no-install\n```\n\nWhen installation is enabled, the tool detects the package manager from the\nproject's `packageManager` field or lockfile. If detection fails without a TTY,\npass `--package-manager ` or `--no-install`.\n\n**Important:** Commit your changes before running migration.\n\n## Key Differences\n\n### Default Values\n\n| Option | tsup | tsdown |\n|--------|------|--------|\n| `format` | `['cjs']` | `['esm']` |\n| `clean` | `false` | `true` |\n| `dts` | `false` | Auto-enabled if `types`/`typings` in package.json |\n| `target` | Manual | Auto-read from `engines.node` in package.json |\n\n### Option Renames\n\n| tsup | tsdown |\n|------|--------|\n| `entryPoints` | `entry` |\n| `cjsInterop` | `cjsDefault` |\n| `esbuildPlugins` | `plugins` |\n| `outExtension` | `outExtensions` |\n| `skipNodeModulesBundle` | `deps: { neverBundle: true }` |\n| `publicDir` | `copy` |\n| `bundle: false` | `unbundle: true` |\n| `removeNodeProtocol: true` | `nodeProtocol: 'strip'` |\n| `injectStyle: true` | `css: { inject: true }` |\n\nThe old names were accepted (with deprecation warnings) up to tsdown v0.22.14 and have been removed since — v0.23+ silently ignores them, so a leftover tsup option won't error. Migrate in two stages: install `tsdown@0.22.14` first and resolve every deprecation warning (a warning-free build proves the mapping is complete), then upgrade to the latest version. The `tsdown-migrate` tool installs v0.22.14 for this reason.\n\n### Deprecated but Compatible Options\n\nThese tsup options still work but emit deprecation warnings and will be removed in a future version — migrate them immediately:\n\n| tsup (deprecated) | tsdown (preferred) |\n|-------------------|--------------------|\n| `external: [...]` | `deps: { neverBundle: [...] }` |\n| `noExternal: [...]` | `deps: { alwaysBundle: [...] }` |\n\ntsdown also adds `deps.onlyBundle` for whitelisting allowed bundled packages.\n\n### Unsupported Options\n\n| Option | Status | Alternative |\n|--------|--------|-------------|\n| `splitting: false` | Always enabled | Code splitting cannot be disabled |\n| `metafile` | Not available | Use `devtools: true` for bundle analysis via Vite DevTools |\n| `swc` | Not supported | tsdown uses oxc for transformation (built-in) |\n| `experimentalDts` | Superseded | Use the `dts` option instead |\n| `legacyOutput` | Not supported | No alternative |\n| `plugins` (tsup experimental) | Incompatible | Migrate to Rolldown plugins |\n\n### Plugin System\n\ntsdown uses Rolldown plugins instead of esbuild plugins. If you use unplugin plugins, update the import path:\n\n```ts\n// Before (tsup)\nimport plugin from 'unplugin-example/esbuild'\n// After (tsdown)\nimport plugin from 'unplugin-example/rolldown'\n```\n\n### Output Filename Differences\n\nFor IIFE builds, `tsdown` emits `[name].iife.js`; `tsup` commonly emitted `[name].global.js`. `outExtensions` customizes extensions or suffixes, but it does not remove `.iife` or `.umd`. Use `outputOptions.entryFileNames: '[name].global.js'` to preserve old IIFE filenames.\n\n### New Features in tsdown\n\n#### Node Protocol Control\n\n```ts\nexport default defineConfig({\n nodeProtocol: true, // Add node: prefix (fs → node:fs)\n nodeProtocol: 'strip', // Remove node: prefix (node:fs → fs)\n nodeProtocol: false, // Keep as-is (default)\n})\n```\n\n#### Better Workspace Support\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*', // Build all packages\n})\n```\n\n#### Other tsdown-Exclusive Features\n\n- **`exports`**: Auto-generate the `exports` field in `package.json` with `exports: true`\n- **`publint`** / **`attw`**: Validate your package for common issues and type correctness\n- **`exe`**: Bundle as a Node.js standalone executable (SEA) with `exe: true`\n- **`devtools`**: Vite DevTools integration for bundle analysis with `devtools: true`\n- **`hooks`**: Lifecycle hooks (`build:prepare`, `build:before`, `build:done`)\n- **`css`**: Full CSS pipeline with preprocessors, Lightning CSS, PostCSS, CSS modules, and code splitting\n- **`globImport`**: Support for `import.meta.glob` (Vite-style glob imports)\n\n## Migration Checklist\n\n1. **Backup your code** - Commit all changes\n2. **Run migration tool** - `npx tsdown-migrate`\n3. **Review changes** - Check modified config files\n4. **Update scripts** - Change `tsup` to `tsdown` in package.json\n5. **Test build** - Run `pnpm build` to verify\n6. **Adjust config** - Fine-tune based on your needs\n\n## Common Migration Patterns\n\n### Basic Library\n\n**Before (tsup):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs', 'esm'],\n dts: true,\n})\n```\n\n**After (tsdown):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'], // ESM now default\n dts: true,\n clean: true, // Now enabled by default\n})\n```\n\n### With Custom Target\n\n**Before (tsup):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n target: 'es2020',\n})\n```\n\n**After (tsdown):**\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n // target auto-reads from package.json engines.node\n // Or override explicitly:\n target: 'es2020',\n})\n```\n\n### CLI Scripts\n\n**Before (package.json):**\n```json\n{\n \"scripts\": {\n \"build\": \"tsup\",\n \"dev\": \"tsup --watch\"\n }\n}\n```\n\n**After (package.json):**\n```json\n{\n \"scripts\": {\n \"build\": \"tsdown\",\n \"dev\": \"tsdown --watch\"\n }\n}\n```\n\n## Feature Compatibility\n\n### Supported tsup Features\n\nMost tsup features are supported:\n- ✅ Multiple entry points\n- ✅ Multiple formats (ESM, CJS, IIFE, UMD)\n- ✅ TypeScript declarations\n- ✅ Source maps\n- ✅ Minification\n- ✅ Watch mode\n- ✅ External dependencies\n- ✅ Tree shaking\n- ✅ Shims\n- ✅ Plugins (Rollup compatible)\n\n### Missing Features\n\nSome tsup features are not yet available. Check [GitHub issues](https://github.com/rolldown/tsdown/issues) for status and request features.\n\n## Troubleshooting\n\n### Build Fails After Migration\n\n1. **Check Node.js version** - Requires Node.js 22.18.0+ to run tsdown itself. The bundled output can still target lower Node.js versions via `target`; if you need to support Node.js 18 / 20, build with Node.js 22+ in CI and test the produced output (or packed tarball) on the lower versions.\n2. **Install TypeScript** - Required for DTS generation\n3. **Review config changes** - Ensure format and options are correct\n4. **Check dependencies** - Verify all dependencies are installed\n\n### Different Output\n\n- **Format order** - tsdown defaults to ESM first\n- **Clean behavior** - tsdown cleans outDir by default\n- **Target** - tsdown auto-detects from package.json\n\n### Performance Issues\n\ntsdown should be faster than tsup. If not:\n1. Enable `isolatedDeclarations` for faster DTS generation\n2. Check for large dependencies being bundled\n3. Use `deps.neverBundle: true` if needed\n\n## Getting Help\n\n- [GitHub Issues](https://github.com/rolldown/tsdown/issues) - Report bugs or request features\n- [Documentation](https://tsdown.dev) - Full documentation\n- [Migration Tool](https://github.com/rolldown/tsdown/tree/main/packages/migrate) - Source code\n\n## Acknowledgements\n\ntsdown is heavily inspired by tsup and incorporates parts of its codebase. Thanks to [@egoist](https://github.com/egoist) and the tsup community.\n\n\n# CJS Default Export\n\nControl how default exports are handled in CommonJS output.\n\n## Overview\n\nThe `cjsDefault` option improves compatibility when generating CommonJS **entry** modules. When enabled (default), entry modules with only a single default export use `module.exports = ...` instead of `exports.default = ...`.\n\n## Type\n\n```ts\ncjsDefault?: boolean // default: true\n```\n\n## Basic Usage\n\n### Enabled (Default)\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n cjsDefault: true, // default behavior\n})\n```\n\n### Disabled\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n cjsDefault: false,\n})\n```\n\n## How It Works\n\n### With `cjsDefault: true` (Default)\n\nWhen your module has **only a single default export**, tsdown transforms:\n\n**Source:**\n```ts\n// src/index.ts\nexport default function greet() {\n console.log('Hello, world!')\n}\n```\n\n**Generated CJS:**\n```js\n// dist/index.cjs\nfunction greet() {\n console.log('Hello, world!')\n}\nmodule.exports = greet\n```\n\n**Generated Declaration:**\n```ts\n// dist/index.d.cts\ndeclare function greet(): void\nexport = greet\n```\n\nThis allows consumers to use `const greet = require('your-module')` directly.\n\n### With `cjsDefault: false`\n\nThe default export stays as `exports.default`:\n\n```js\n// dist/index.cjs\nfunction greet() {\n console.log('Hello, world!')\n}\nexports.default = greet\n```\n\nConsumers need `require('your-module').default`.\n\n## Entry Modules Only\n\n`cjsDefault` only applies to **explicit entry modules**. In [unbundle mode](option-unbundle.md), imported modules that are emitted as non-entry chunks keep named CJS exports such as `exports.default`. CJS is considered legacy and is supported in maintenance-only mode, so this behavior will not be extended to non-entry chunks.\n\nIf every source module is intended to be consumed independently, include all of them as entries:\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts'],\n root: 'src',\n format: 'cjs',\n unbundle: true,\n})\n```\n\n## When to Disable\n\n- When your module has both default and named exports\n- When you need consistent `exports.default` behavior\n- When consumers always use ESM imports\n\n## Tips\n\n1. **Leave enabled** for most libraries (default `true`)\n2. **Disable** if you have both default and named exports and need consistent behavior\n3. **Test CJS consumers** to verify compatibility\n\n## Related Options\n\n- [Output Format](option-output-format.md) - Module formats\n- [Shims](option-shims.md) - ESM/CJS compatibility\n\n\n# Output Directory Cleaning\n\nControl how the output directory is cleaned before builds.\n\n## Overview\n\nBy default, tsdown **cleans the output directory** before each build to remove stale files from previous builds.\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Clean enabled (default)\ntsdown\n\n# Disable cleaning\ntsdown --no-clean\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n clean: true, // Default\n})\n```\n\n## Behavior\n\n### With Cleaning (Default)\n\nBefore each build:\n1. All files in `outDir` are removed\n2. Fresh build starts with empty directory\n3. Only current build outputs remain\n\n**Benefits:**\n- No stale files\n- Predictable output\n- Clean slate each build\n\n### Without Cleaning\n\nBuild outputs are added to existing files:\n\n```ts\nexport default defineConfig({\n clean: false,\n})\n```\n\n**Use when:**\n- Multiple builds to same directory\n- Incremental builds\n- Preserving other files\n- Watch mode (faster rebuilds)\n\n## Common Patterns\n\n### Production Build\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n clean: true, // Ensure clean output\n minify: true,\n})\n```\n\n### Development Mode\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n clean: !options.watch, // Don't clean in watch mode\n sourcemap: options.watch,\n}))\n```\n\n### Multiple Builds\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true, // Clean once\n },\n {\n entry: ['src/cli.ts'],\n outDir: 'dist',\n clean: false, // Don't clean, add to same dir\n },\n])\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n clean: true, // Clean each package's dist\n})\n```\n\n### Preserve Static Files\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n clean: false, // Keep manually added files\n outDir: 'dist',\n})\n\n// Manually copy files first\n// Then run tsdown --no-clean\n```\n\n## Clean Patterns\n\n### Selective Cleaning\n\n```ts\nimport { rmSync } from 'fs'\n\nexport default defineConfig({\n clean: false, // Disable auto clean\n hooks: {\n 'build:prepare': () => {\n // Custom cleaning logic\n rmSync('dist/*.js', { force: true })\n // Keep other files\n },\n },\n})\n```\n\n### Clean Specific Directories\n\n```ts\nexport default defineConfig({\n clean: false,\n hooks: {\n 'build:prepare': async () => {\n const { rm } = await import('fs/promises')\n // Only clean specific subdirectories\n await rm('dist/esm', { recursive: true, force: true })\n await rm('dist/cjs', { recursive: true, force: true })\n // Keep dist/types\n },\n },\n})\n```\n\n## Watch Mode Behavior\n\nIn watch mode, cleaning behavior is important:\n\n### Clean on First Build Only\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n watch: options.watch,\n clean: !options.watch, // Only clean initial build\n}))\n```\n\n**Result:**\n- First build: Clean\n- Subsequent rebuilds: Incremental\n\n### Always Clean\n\n```ts\nexport default defineConfig({\n watch: true,\n clean: true, // Clean every rebuild\n})\n```\n\n**Trade-off:** Slower rebuilds, but always fresh output.\n\n## Tips\n\n1. **Leave enabled** for production builds\n2. **Disable in watch mode** for faster rebuilds\n3. **Use multiple configs** carefully with cleaning\n4. **Custom clean logic** via hooks if needed\n5. **Be cautious** - cleaning removes ALL files in outDir\n6. **Test cleaning** - ensure no important files are lost\n\n## Troubleshooting\n\n### Important Files Deleted\n\n- Don't put non-build files in outDir\n- Use separate directory for static files\n- Disable cleaning and manage manually\n\n### Stale Files in Output\n\n- Enable cleaning: `clean: true`\n- Or manually remove before build\n\n### Slow Rebuilds in Watch\n\n- Disable cleaning in watch mode\n- Use incremental builds\n\n## CLI Examples\n\n```bash\n# Default (clean enabled)\ntsdown\n\n# Disable cleaning\ntsdown --no-clean\n\n# Watch mode without cleaning\ntsdown --watch --no-clean\n\n# Multiple formats with cleaning\ntsdown --format esm,cjs --clean\n```\n\n## Examples\n\n### Safe Production Build\n\n```bash\n# Clean before build\nrm -rf dist\ntsdown --clean\n```\n\n### Incremental Development\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n watch: true,\n clean: false, // Faster rebuilds\n sourcemap: true,\n})\n```\n\n### Multi-Stage Build\n\n```ts\n// Stage 1: Clean and build main\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true,\n },\n {\n entry: ['src/utils.ts'],\n outDir: 'dist',\n clean: false, // Add to same directory\n },\n])\n```\n\n## Related Options\n\n- [Output Directory](option-output-directory.md) - Configure outDir\n- [Watch Mode](option-watch-mode.md) - Development workflow\n- [Hooks](advanced-hooks.md) - Custom clean logic\n- [Entry](option-entry.md) - Entry points\n\n\n# Configuration File\n\nCentralize and manage build settings with a configuration file.\n\n## Overview\n\ntsdown searches for config files automatically in the current directory and parent directories.\n\n## Supported File Names\n\ntsdown looks for these files (in order):\n- `tsdown.config.ts`\n- `tsdown.config.mts`\n- `tsdown.config.cts`\n- `tsdown.config.js`\n- `tsdown.config.mjs`\n- `tsdown.config.cjs`\n- `tsdown.config.json`\n- `tsdown.config`\n- `package.json` (in `tsdown` field)\n\n## Basic Configuration\n\n### TypeScript Config\n\n```ts\n// tsdown.config.ts\nimport { defineConfig } from 'tsdown'\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n})\n```\n\n### JavaScript Config\n\n```js\n// tsdown.config.js\nexport default {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n}\n```\n\n### JSON Config\n\n```json\n// tsdown.config.json\n{\n \"entry\": [\"src/index.ts\"],\n \"format\": [\"esm\", \"cjs\"],\n \"dts\": true\n}\n```\n\n### Package.json Config\n\n```json\n// package.json\n{\n \"name\": \"my-library\",\n \"tsdown\": {\n \"entry\": [\"src/index.ts\"],\n \"format\": [\"esm\", \"cjs\"],\n \"dts\": true\n }\n}\n```\n\n## Multiple Configurations\n\nBuild multiple outputs with different settings:\n\n```ts\nexport default defineConfig([\n {\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n platform: 'node',\n dts: true,\n },\n {\n entry: 'src/browser.ts',\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n minify: true,\n },\n])\n```\n\nEach configuration runs as a separate build.\n\n## Dynamic Configuration\n\nUse a function for conditional config:\n\n```ts\nexport default defineConfig((options) => {\n const isDev = options.watch\n\n return {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !isDev,\n sourcemap: isDev,\n clean: !isDev,\n }\n})\n```\n\nAvailable options:\n- `watch` - Whether watch mode is enabled\n- Other CLI flags passed to config\n\n## Config Loaders\n\nControl how TypeScript config files are loaded:\n\n### Auto Loader (Default)\n\nUses native TypeScript support if available, otherwise falls back to `unrun`:\n\n```bash\ntsdown # Uses auto loader\n```\n\n### Native Loader\n\nUses runtime's native TypeScript support (Node.js 22.18.0+, Bun, Deno):\n\n```bash\ntsdown --config-loader native\n```\n\n### tsx Loader\n\nUses [tsx](https://tsx.is/) library for loading via its tsImport API. Note: `tsx` is an optional peer dependency — install it manually first.\n\n```bash\npnpm add -D tsx\ntsdown --config-loader tsx\n```\n\n### Unrun Loader\n\nUses [unrun](https://gugustinette.github.io/unrun/) library for loading. Note: `unrun` is an optional peer dependency — install it manually first.\n\n```bash\npnpm add -D unrun\ntsdown --config-loader unrun\n```\n\n**Tip:** Use `tsx` or `unrun` loader if you need to load TypeScript configs without file extensions in Node.js.\n\n## Custom Config Path\n\nSpecify a custom config file location:\n\n```bash\ntsdown --config ./configs/build.config.ts\n# or\ntsdown -c custom-config.ts\n```\n\n## Disable Config File\n\nIgnore config files and use CLI options only:\n\n```bash\ntsdown --no-config src/index.ts --format esm\n```\n\n## Extend Vite/Vitest Config (Experimental)\n\nReuse existing Vite or Vitest configurations:\n\n```bash\n# Extend vite.config.*\ntsdown --from-vite\n\n# Extend vitest.config.*\ntsdown --from-vite vitest\n```\n\n**Note:** Only specific options like `resolve` and `plugins` are reused. Test thoroughly as this feature is experimental.\n\n## Workspace / Monorepo\n\nBuild multiple packages with a single config:\n\n```ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nEach package directory matching the glob pattern will be built with the same configuration.\n\n## Common Patterns\n\n### Library with Multiple Builds\n\n```ts\nexport default defineConfig([\n // Node.js build\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n platform: 'node',\n dts: true,\n },\n // Browser build\n {\n entry: ['src/browser.ts'],\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n },\n])\n```\n\n### Development vs Production\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: !options.watch,\n sourcemap: options.watch ? true : false,\n clean: !options.watch,\n}))\n```\n\n### Monorepo Root Config\n\n```ts\n// Root tsdown.config.ts\nexport default defineConfig({\n workspace: 'packages/*',\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n clean: true,\n // Shared config for all packages\n})\n```\n\n### Per-Package Override\n\n```ts\n// packages/special/tsdown.config.ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm'], // Override: only ESM\n platform: 'browser', // Override: browser only\n})\n```\n\n## Config Precedence\n\nWhen multiple configs exist:\n\n1. CLI options (highest priority)\n2. Config file specified with `--config`\n3. Auto-discovered config files\n4. Package.json `tsdown` field\n5. Default values\n\n## Tips\n\n1. **Use TypeScript config** for type checking and autocomplete\n2. **Use defineConfig** helper for better DX\n3. **Export arrays** for multiple build configurations\n4. **Use functions** for dynamic/conditional configs\n5. **Keep configs simple** - prefer convention over configuration\n6. **Use workspace** for monorepo builds\n7. **Test experimental features** thoroughly before production use\n\n## Related Options\n\n- [Entry](option-entry.md) - Configure entry points\n- [Output Format](option-output-format.md) - Output formats\n- [Watch Mode](option-watch-mode.md) - Watch mode configuration\n\n\n# Copy Files\n\nCopy static files and directories into the build output.\n\n## Overview\n\nThe `copy` option copies assets that should be distributed without being processed by the bundler — images, fonts, license files, etc.\n\n## Basic Usage\n\n### CLI\n\n```bash\ntsdown --copy public\n```\n\nWith the default `outDir` of `dist`, `public/favicon.svg` is copied to `dist/public/favicon.svg`.\n\n### Config File\n\n```ts\nexport default defineConfig({\n copy: 'public',\n})\n```\n\nMultiple paths, glob patterns, or object entries in an array:\n\n```ts\nexport default defineConfig({\n copy: [\n 'LICENSE',\n {\n from: ['public/**/*', '!public/**/*.map'],\n to: 'dist/assets',\n flatten: false,\n },\n ],\n})\n```\n\nGlob patterns support negation with a leading `!`.\n\n**Note:** Relative source and destination paths are resolved from the project root (`cwd`), not from `outDir`.\n\n## Object Options\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `from` | `string \\| string[]` | Required | Source path or glob pattern; arrays can include negated patterns |\n| `to` | `string` | `outDir` | Destination path, resolved from the project root |\n| `flatten` | `boolean` | `true` | Place matched files directly in `to`. Set `false` to preserve the directory structure below the first segment |\n| `rename` | `string \\| ((name, extension, fullPath) => string)` | — | Change the destination name. Callback receives the extension without a leading dot and the absolute path |\n| `verbose` | `boolean` | `false` | Log each copied source and destination |\n\n### Preserve Directory Structure\n\n```ts\nexport default defineConfig({\n copy: {\n from: 'assets/**/*',\n to: 'dist/public',\n flatten: false,\n },\n})\n```\n\n`assets/fonts/inter.woff2` → `dist/public/fonts/inter.woff2`.\n\n### Rename Copied Items\n\n```ts\nexport default defineConfig({\n copy: [\n { from: 'src/file.txt', to: 'dist', rename: 'file.md' },\n {\n from: 'src/file.txt',\n to: 'dist',\n rename: (name, extension) => `${name}-renamed.${extension}`,\n },\n ],\n})\n```\n\nCreates `dist/file.md` and `dist/file-renamed.txt`.\n\n## Dynamic Configuration\n\n`copy` can be a sync or async callback receiving the resolved tsdown config:\n\n```ts\nexport default defineConfig({\n copy: ({ outDir }) => ({\n from: ['assets/**/*', '!assets/**/*.map'],\n to: `${outDir}/assets`,\n flatten: false,\n }),\n})\n```\n\n## Build and Watch Behavior\n\n- Copying runs after the bundle output is produced; files are copied without passing through Rolldown transforms.\n- A top-level `copy` option runs only once for a multi-format build; a format-specific override can define `copy` again for that format.\n- In watch mode, matched source files are watched as build dependencies — changing one triggers a rebuild and copies the current files again.\n\n## Related Options\n\n- [Output Directory](option-output-directory.md) - Where output goes\n- [Cleaning](option-cleaning.md) - Output directory cleanup\n- [Watch Mode](option-watch-mode.md) - Watch mode behavior\n\n\n# CSS Support\n\n**Status: Experimental — API and behavior may change.**\n\nConfigure CSS handling including preprocessors, syntax lowering, minification, and code splitting.\n\n## Getting Started\n\nAll CSS support in `tsdown` is provided by the `@tsdown/css` package. Install it to enable CSS handling:\n\n```bash\nnpm install -D @tsdown/css\n```\n\nWhen `@tsdown/css` is installed, CSS processing is automatically enabled. Without it, encountering CSS files will result in an error.\n\n## CSS Import\n\nImport `.css` files from TypeScript/JavaScript — CSS is extracted into separate `.css` assets:\n\n```ts\n// src/index.ts\nimport './style.css'\nexport function greet() { return 'Hello' }\n```\n\nOutput: `index.mjs` + `index.css`\n\n### `@import` Inlining\n\nCSS `@import` statements are resolved and inlined automatically. No separate output files produced.\n\n### Inline CSS (`?inline`)\n\nAppend `?inline` to return processed CSS as a JS string instead of emitting a `.css` file:\n\n```ts\nimport './style.css' // → .css file\nimport css from './theme.css?inline' // → JS string\n```\n\nWorks with preprocessors too (`./foo.scss?inline`). Goes through full pipeline (preprocessors, @import inlining, lowering, minification). Tree-shakeable (`moduleSideEffects: false`).\n\n## CSS Pre-processors\n\nBuilt-in support for Sass, Less, and Stylus. Install the preprocessor:\n\n```bash\n# Sass (either one)\nnpm install -D sass-embedded # recommended, faster\nnpm install -D sass\n\n# Less\nnpm install -D less\n\n# Stylus\nnpm install -D stylus\n```\n\nThen import directly:\n\n```ts\nimport './style.scss'\nimport './theme.less'\nimport './global.styl'\n```\n\n### Preprocessor Options\n\n```ts\nexport default defineConfig({\n css: {\n preprocessorOptions: {\n scss: {\n additionalData: `$brand-color: #ff7e17;`,\n },\n less: {\n math: 'always',\n },\n stylus: {\n define: { '$brand-color': '#ff7e17' },\n },\n },\n },\n})\n```\n\n### `additionalData`\n\nInject code at the beginning of every preprocessor file:\n\n```ts\n// String form\nscss: {\n additionalData: `@use \"src/styles/variables\" as *;`,\n}\n\n// Function form\nscss: {\n additionalData: (source, filename) => {\n if (filename.includes('theme')) return source\n return `@use \"src/styles/variables\" as *;\\n${source}`\n },\n}\n```\n\n## CSS Minification\n\n```ts\nexport default defineConfig({\n css: {\n minify: true,\n },\n})\n```\n\nPowered by Lightning CSS.\n\n## CSS Target\n\nOverride the top-level `target` specifically for CSS:\n\n```ts\nexport default defineConfig({\n target: 'node18',\n css: {\n target: 'chrome90', // CSS-specific target\n },\n})\n```\n\nSet `css.target: false` to disable CSS syntax lowering entirely.\n\n## CSS Transformer\n\n`css.transformer` controls mutually exclusive CSS processing paths:\n\n- `'lightningcss'` (default): `@import` via Lightning CSS `bundleAsync()`, no PostCSS.\n- `'postcss'`: `@import` via `postcss-import`, PostCSS plugins applied, Lightning CSS for final transform only.\n\n```ts\nexport default defineConfig({\n css: {\n transformer: 'postcss',\n },\n})\n```\n\n### PostCSS Options\n\n```ts\nexport default defineConfig({\n css: {\n transformer: 'postcss',\n postcss: {\n plugins: [require('autoprefixer')],\n },\n // Or: postcss: './config' — path to search for postcss.config.js\n },\n})\n```\n\nAuto-detects PostCSS config from project root when `transformer` is `'postcss'` and `css.postcss` is omitted.\n\n## Lightning CSS (Syntax Lowering)\n\nInstall `lightningcss` to enable CSS syntax lowering based on your `target`:\n\n```bash\nnpm install -D lightningcss\n```\n\nWhen `target` is set (e.g., `target: 'chrome108'`), modern CSS features are automatically downleveled:\n\n```css\n/* Input */\n.foo { & .bar { color: red } }\n\n/* Output (chrome108) */\n.foo .bar { color: red }\n```\n\n### Custom Lightning CSS Options\n\n```ts\nimport { Features } from 'lightningcss'\n\nexport default defineConfig({\n css: {\n lightningcss: {\n targets: { chrome: 100 << 16 },\n include: Features.Nesting,\n },\n },\n})\n```\n\n`css.lightningcss.targets` takes precedence over both `target` and `css.target` for CSS.\n\n## CSS Modules\n\nFiles with `.module.css` (and `.module.scss`, `.module.less`, etc.) are treated as CSS modules — class names are scoped and exported as JS:\n\n```ts\nimport styles from './app.module.css'\nconsole.log(styles.title) // \"scoped_title_hash\"\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n css: {\n modules: {\n scopeBehaviour: 'local', // 'local' (default) | 'global'\n generateScopedName: '[hash]_[local]', // Lightning CSS pattern string\n localsConvention: 'camelCase', // 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly'\n },\n },\n})\n```\n\nSet `css.modules: false` to disable. Function-form `generateScopedName` requires `transformer: 'postcss'`.\n\n`localsConvention` also accepts a function compatible with Vite and\n`postcss-modules`:\n\n```ts\nexport default defineConfig({\n css: {\n modules: {\n localsConvention: (\n originalClassName,\n generatedClassName,\n inputFile,\n ) => originalClassName.replaceAll(/-([a-z0-9])/g, (_, c) => c.toUpperCase()),\n },\n },\n})\n```\n\nThe function form works with both CSS transformers and returns the JavaScript\nexport key.\n\n### Optional Dependencies (PostCSS path)\n\n```bash\nnpm install -D postcss postcss-modules\n```\n\n## Code Splitting\n\n### Merged (Default)\n\nAll CSS merged into a single file (default: `style.css`).\n\n```ts\nexport default defineConfig({\n css: {\n fileName: 'my-library.css', // Custom name (default: 'style.css')\n },\n})\n```\n\n### Per-Chunk Splitting\n\n```ts\nexport default defineConfig({\n css: {\n splitting: true, // Each JS chunk gets a corresponding .css file\n },\n})\n```\n\n## Preserving CSS Imports (`css.inject`)\n\nWhen enabled, JS output preserves `import` statements pointing to emitted CSS files. Consumers auto-import CSS alongside JS:\n\n```ts\nexport default defineConfig({\n css: {\n inject: true,\n },\n})\n```\n\n## PostCSS Optional Peer Dependencies\n\nWhen using `transformer: 'postcss'`, install these as needed:\n\n| Package | Purpose | Required When |\n|---------|---------|---------------|\n| `postcss` | Core PostCSS engine | Always (with `transformer: 'postcss'`) |\n| `postcss-import` | Resolve/inline `@import` | CSS uses `@import` |\n| `postcss-modules` | CSS modules (scoped classes) | Using `.module.css` files |\n\n```bash\nnpm install -D postcss postcss-import postcss-modules\n```\n\nAll declared as optional peer dependencies of `@tsdown/css`.\n\n## Options Reference\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `css.transformer` | `'postcss' \\| 'lightningcss'` | `'lightningcss'` | CSS processing pipeline |\n| `css.splitting` | `boolean` | `false` | Per-chunk CSS splitting |\n| `css.fileName` | `string` | `'style.css'` | Merged CSS file name |\n| `css.minify` | `boolean` | `false` | CSS minification |\n| `css.modules` | `object \\| false` | `{}` | CSS modules config, or `false` to disable |\n| `css.inject` | `boolean` | `false` | Preserve CSS imports in JS output |\n| `css.target` | `string \\| string[] \\| false` | _from `target`_ | CSS-specific lowering target |\n| `css.postcss` | `string \\| object` | — | PostCSS config path or inline options |\n| `css.preprocessorOptions` | `object` | — | Preprocessor options |\n| `css.lightningcss` | `object` | — | Lightning CSS options |\n\n## Related\n\n- [Target](option-target.md) - Configure syntax lowering targets\n- [Output Format](option-output-format.md) - Module output formats\n\n\n# Dependencies\n\nControl how dependencies are bundled or externalized.\n\n## Overview\n\ntsdown intelligently handles dependencies to keep your library lightweight while ensuring all necessary code is included.\n\n## Default Behavior\n\n### Auto-Externalized\n\nThese are **NOT bundled** by default:\n\n- **`dependencies`** - Installed automatically with your package\n- **`peerDependencies`** - User must install manually\n- **`optionalDependencies`** - May or may not be installed depending on platform/config\n\n### Conditionally Bundled\n\nThese are **bundled ONLY if imported**:\n\n- **`devDependencies`** - Only if actually used in source code\n- **Phantom dependencies** - In node_modules but not in package.json\n\n## Configuration Options\n\nAll dependency options are grouped under the `deps` field:\n\n```ts\nexport default defineConfig({\n deps: {\n neverBundle: ['react', /^@myorg\\//],\n alwaysBundle: ['some-package'],\n onlyBundle: ['cac', 'bumpp'],\n onlyImport: ['cac'],\n resolveDepSubpath: true,\n },\n})\n```\n\n### `deps.neverBundle`\n\nMark dependencies as external (not bundled):\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: [\n 'react', // Single package\n 'react-dom',\n /^@myorg\\//, // Regex pattern (all @myorg/* packages)\n /^lodash/, // All lodash packages\n ],\n },\n})\n```\n\nSet to `true` to externalize ALL dependencies:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n neverBundle: true,\n },\n})\n```\n\n**Result:** Every import that follows npm package naming conventions is externalized as written, without being resolved. This is fast and even works when dependencies are not installed. Subpaths like `my-dep/utils` are preserved exactly unless `resolveDepSubpath` is enabled. Other non-relative imports (`#` subpath imports, path aliases like `~/`) are resolved: they stay external if they resolve into node_modules, and are bundled if they map to local files. Combine with `alwaysBundle` to bundle selected dependencies.\n\n### `deps.alwaysBundle`\n\nForce dependencies to be bundled:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n alwaysBundle: [\n 'some-package', // Bundle this even if in dependencies\n 'vendor-lib',\n ],\n },\n})\n```\n\n### `deps.onlyBundle`\n\nWhitelist of dependencies allowed to be bundled from node_modules. Throws an error if any unlisted dependency is bundled:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n onlyBundle: [\n 'cac', // Allow bundling cac\n 'bumpp', // Allow bundling bumpp\n /^my-utils/, // Regex patterns supported\n ],\n },\n})\n```\n\n**Behavior:**\n- **Array** (`['cac', /^my-/]`): Only matching dependencies can be bundled. Error for others.\n- **`false`**: Suppress all warnings about bundled dependencies.\n- **Not set** (default): Warns if any node_modules dependencies are bundled.\n\n**Note:** Include all sub-dependencies in the list, not just top-level imports.\n\n### `deps.onlyImport`\n\nWhitelist of packages the emitted output is allowed to import at runtime. Throws an error (listing all violations) if any chunk imports an unlisted package:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n deps: {\n onlyImport: [\n 'cac', // Also covers subpath imports like cac/deno\n /^my-utils/, // Regex patterns match the package name\n ],\n },\n})\n```\n\n**Behavior:**\n- Matching is based on the package name; subpath imports (`cac/deno`) match `cac`.\n- Node.js built-in modules are always allowed when `platform` is `node`.\n- Relative imports between code-split chunks are always allowed.\n- Declaration output (`.d.ts`) is checked too.\n\n**Limitation:** ES imports and dynamic `import()` expressions are checked. CJS `require()` calls are not detected.\n\n### `deps.resolveDepSubpath`\n\nBy default, tsdown preserves external dependency subpath imports as written. Enable `resolveDepSubpath` to resolve subpath imports to their actual package-relative paths when a package has no `exports` field. For example, `my-dep/functions/lt` may become `my-dep/functions/lt.js`, and `my-dep/folder` may become `my-dep/folder/index.js`.\n\n```ts\nexport default defineConfig({\n deps: {\n resolveDepSubpath: true, // default: false\n },\n})\n```\n\n## Common Patterns\n\n### React Component Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.tsx'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n 'react',\n 'react-dom',\n /^react\\//, // react/jsx-runtime, etc.\n ],\n },\n dts: true,\n})\n```\n\n### Utility Library with Shared Deps\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n alwaysBundle: ['lodash-es'],\n },\n dts: true,\n})\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n /^@mycompany\\//, // Don't bundle other workspace packages\n ],\n },\n dts: true,\n})\n```\n\n### CLI Tool (Bundle Everything)\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n format: ['esm'],\n platform: 'node',\n deps: {\n alwaysBundle: [/.*/],\n },\n shims: true,\n})\n```\n\n### Library with Specific Externals\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n deps: {\n neverBundle: [\n 'vue',\n '@vue/runtime-core',\n '@vue/reactivity',\n ],\n },\n dts: true,\n})\n```\n\n## Declaration Files\n\nDependency handling for `.d.ts` files follows the same rules as JavaScript.\n\n### Complex Type Resolution\n\nUse TypeScript resolver for complex third-party types:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n dts: {\n resolver: 'tsc', // Use TypeScript resolver instead of Oxc\n },\n})\n```\n\n**When to use `tsc` resolver:**\n- Types in `@types/*` packages with non-standard naming (e.g., `@types/babel__generator`)\n- Complex type dependencies\n- Issues with default Oxc resolver\n\n**Trade-off:** `tsc` is slower but more compatible.\n\n## CLI Usage\n\n### Never Bundle\n\n```bash\ntsdown --deps.never-bundle react --deps.never-bundle react-dom\ntsdown --deps.never-bundle '/^@myorg\\/.*/'\n```\n\n## Migration from Deprecated Options\n\n| Deprecated Option | New Option |\n|---|---|\n| `external` | `deps.neverBundle` |\n| `noExternal` | `deps.alwaysBundle` |\n\n## Examples by Use Case\n\n### Framework Component\n\n```ts\n// Don't bundle framework\nexport default defineConfig({\n deps: {\n neverBundle: ['vue', 'react', 'solid-js', 'svelte'],\n },\n})\n```\n\n### Standalone App\n\n```ts\n// Bundle everything\nexport default defineConfig({\n deps: {\n alwaysBundle: [/.*/],\n },\n})\n```\n\n### Shared Library\n\n```ts\n// Bundle only specific utils\nexport default defineConfig({\n deps: {\n neverBundle: [/.*/], // External by default\n alwaysBundle: ['tiny-utils'], // Except this one\n },\n})\n```\n\n### Monorepo Package\n\n```ts\n// External workspace packages, bundle utilities\nexport default defineConfig({\n deps: {\n neverBundle: [\n /^@workspace\\//, // Other workspace packages\n 'react',\n 'react-dom',\n ],\n alwaysBundle: [\n 'lodash-es', // Bundle utility libraries\n ],\n },\n})\n```\n\n## Troubleshooting\n\n### Dependency Bundled Unexpectedly\n\nCheck if it's in `devDependencies` and imported. Move to `dependencies`:\n\n```json\n{\n \"dependencies\": {\n \"should-be-external\": \"^1.0.0\"\n }\n}\n```\n\nOr explicitly externalize:\n\n```ts\nexport default defineConfig({\n deps: {\n neverBundle: ['should-be-external'],\n },\n})\n```\n\n### Missing Dependency at Runtime\n\nEnsure it's in `dependencies`, `peerDependencies`, or `optionalDependencies`:\n\n```json\n{\n \"dependencies\": {\n \"needed-package\": \"^1.0.0\"\n }\n}\n```\n\nOr bundle it:\n\n```ts\nexport default defineConfig({\n deps: {\n alwaysBundle: ['needed-package'],\n },\n})\n```\n\n### Type Resolution Errors\n\nUse TypeScript resolver for complex types:\n\n```ts\nexport default defineConfig({\n dts: {\n resolver: 'tsc',\n },\n})\n```\n\n## Summary\n\n**Default behavior:**\n- `dependencies`, `peerDependencies`, & `optionalDependencies` → External\n- `devDependencies` & phantom deps → Bundled if imported\n\n**Override (under `deps`):**\n- `neverBundle` → Force external\n- `alwaysBundle` → Force bundled\n- `onlyBundle` → Whitelist bundled deps\n- `onlyImport` → Whitelist runtime imports in output\n- `neverBundle: true` → Externalize all dependencies\n- `resolveDepSubpath: true` → Resolve external dependency subpath imports to package-relative paths\n\n**Declaration files:**\n- Same bundling logic as JavaScript\n- Use `resolver: 'tsc'` for complex types\n\n## Tips\n\n1. **Keep dependencies external** for libraries\n2. **Bundle everything** for standalone CLIs\n3. **Use regex patterns** for namespaced packages\n4. **Check bundle size** to verify external/bundled split\n5. **Test with fresh install** to catch missing dependencies\n6. **Use tsc resolver** only when needed (slower)\n\n## Related Options\n\n- [External](option-dependencies.md) - This page\n- [Platform](option-platform.md) - Runtime environment\n- [Output Format](option-output-format.md) - Module formats\n- [DTS](option-dts.md) - Type declarations\n\n\n# TypeScript Declaration Files\n\nGenerate `.d.ts` type declaration files for your library.\n\n## Overview\n\ntsdown uses [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts) to generate and bundle TypeScript declaration files.\n\n**Requirements:**\n- TypeScript must be installed in your project\n\n## Enabling DTS Generation\n\n### Auto-Enabled\n\nDTS generation is **automatically enabled** if `package.json` contains:\n- `types` field, or\n- `typings` field\n\n### Manual Enable\n\n#### CLI\n\n```bash\ntsdown --dts\n```\n\n#### Config File\n\n```ts\nexport default defineConfig({\n dts: true,\n})\n```\n\n## Performance\n\n### With `isolatedDeclarations` (Recommended)\n\n**Extremely fast** - uses oxc-transform for generation.\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"isolatedDeclarations\": true\n }\n}\n```\n\n### Without `isolatedDeclarations`\n\nFalls back to TypeScript compiler. Reliable but slower.\n\n## Declaration Maps\n\nMap `.d.ts` files back to original `.ts` sources (useful for monorepos).\n\n### Enable in tsconfig.json\n\n```json\n{\n \"compilerOptions\": {\n \"declarationMap\": true\n }\n}\n```\n\n### Enable in tsdown Config\n\n```ts\nexport default defineConfig({\n dts: {\n sourcemap: true,\n },\n})\n```\n\n## Advanced Options\n\n### Custom Compiler Options\n\nOverride TypeScript compiler options:\n\n```ts\nexport default defineConfig({\n dts: {\n compilerOptions: {\n removeComments: false,\n },\n },\n})\n```\n\n## Build Process\n\n- **ESM format**: `.js` and `.d.ts` files generated in same build\n- **CJS format**: Separate build process for `.d.ts` files\n\n## Common Patterns\n\n### Basic Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nOutput:\n- `dist/index.mjs`\n- `dist/index.cjs`\n- `dist/index.d.ts`\n\n### Multiple Entry Points\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\nOutput:\n- `dist/index.mjs`, `dist/index.cjs`, `dist/index.d.ts`\n- `dist/utils.mjs`, `dist/utils.cjs`, `dist/utils.d.ts`\n\n### With Monorepo Support\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: {\n sourcemap: true, // Enable declaration maps\n },\n})\n```\n\n### Fast Build (Isolated Declarations)\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"isolatedDeclarations\": true,\n \"declaration\": true,\n \"declarationMap\": true\n }\n}\n```\n\n```ts\n// tsdown.config.ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n dts: true, // Will use fast oxc-transform\n})\n```\n\n## Troubleshooting\n\n### Missing Types\n\nEnsure TypeScript is installed:\n\n```bash\npnpm add -D typescript\n```\n\n### Slow Generation\n\nEnable `isolatedDeclarations` in `tsconfig.json` for faster builds.\n\n### Declaration Errors\n\nCheck that all exports have explicit types (required for `isolatedDeclarations`).\n\n### Report Issues\n\nFor DTS-specific issues, report to [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts/issues).\n\n### Vue Support\n\nEnable Vue component type generation (requires `vue-tsc`):\n\n```ts\nexport default defineConfig({\n dts: {\n vue: true,\n },\n})\n```\n\n### Oxc Transform\n\nControl Oxc usage for declaration generation:\n\n```ts\nexport default defineConfig({\n dts: {\n oxc: true, // Use oxc-transform (fast, requires isolatedDeclarations)\n },\n})\n```\n\n### Custom TSConfig\n\nSpecify a different tsconfig for DTS generation:\n\n```ts\nexport default defineConfig({\n dts: {\n tsconfig: './tsconfig.build.json',\n },\n})\n```\n\n## Available DTS Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `sourcemap` | `boolean` | Generate declaration source maps |\n| `compilerOptions` | `object` | Override TypeScript compiler options |\n| `vue` | `boolean` | Enable Vue type generation (requires vue-tsc) |\n| `oxc` | `boolean` | Use oxc-transform for fast generation |\n| `tsconfig` | `string` | Path to tsconfig file |\n| `resolver` | `'oxc' \\| 'tsc'` | Module resolver: `'oxc'` (default, fast) or `'tsc'` (more compatible) |\n| `cjsDefault` | `boolean` | CJS default export handling |\n| `sideEffects` | `boolean` | Preserve side effects in declarations |\n\n## Tips\n\n1. **Always enable DTS** for TypeScript libraries\n2. **Use isolatedDeclarations** for fast builds\n3. **Enable declaration maps** in monorepos\n4. **Ensure explicit types** for all exports\n5. **Install TypeScript** as dev dependency\n\n## Related Options\n\n- [Entry](option-entry.md) - Configure entry points\n- [Output Format](option-output-format.md) - Multiple output formats\n- [Target](option-target.md) - JavaScript version\n\n\n# Entry Points\n\nConfigure which files to bundle as entry points.\n\n## Overview\n\nEntry points are the starting files for the bundling process. Each entry point generates a separate bundle.\n\n## Usage Patterns\n\n### CLI\n\n```bash\n# Single entry\ntsdown src/index.ts\n\n# Multiple entries\ntsdown src/index.ts src/cli.ts\n\n# Glob patterns\ntsdown 'src/*.ts'\n```\n\n### Config File\n\n#### Single Entry\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n})\n```\n\n#### Multiple Entries (Array)\n\n```ts\nexport default defineConfig({\n entry: ['src/entry1.ts', 'src/entry2.ts'],\n})\n```\n\n#### Named Entries (Object)\n\n```ts\nexport default defineConfig({\n entry: {\n main: 'src/index.ts',\n utils: 'src/utils.ts',\n cli: 'src/cli.ts',\n },\n})\n```\n\nOutput files will match the keys:\n- `dist/main.mjs`\n- `dist/utils.mjs`\n- `dist/cli.mjs`\n\n## Glob Patterns\n\nMatch multiple files dynamically using glob patterns:\n\n### All TypeScript Files\n\n```ts\nexport default defineConfig({\n entry: 'src/**/*.ts',\n})\n```\n\n### Exclude Test Files\n\n```ts\nexport default defineConfig({\n entry: ['src/*.ts', '!src/*.test.ts'],\n})\n```\n\n### Object Entries with Glob Patterns\n\nUse glob wildcards (`*`) in both keys and values. The `*` in the key acts as a placeholder replaced with the matched file name (without extension):\n\n```ts\nexport default defineConfig({\n entry: {\n // Maps src/foo.ts → dist/lib/foo.js, src/bar.ts → dist/lib/bar.js\n 'lib/*': 'src/*.ts',\n },\n})\n```\n\n#### Negation Patterns in Object Entries\n\nValues can be an array with negation patterns (`!`):\n\n```ts\nexport default defineConfig({\n entry: {\n 'hooks/*': ['src/hooks/*.ts', '!src/hooks/index.ts'],\n },\n})\n```\n\nMultiple positive and negation patterns:\n\n```ts\nexport default defineConfig({\n entry: {\n 'utils/*': [\n 'src/utils/*.ts',\n 'src/utils/*.tsx',\n '!src/utils/index.ts',\n '!src/utils/internal.ts',\n ],\n },\n})\n```\n\n**Warning:** Multiple positive patterns in an array value must share the same base directory.\n\n### Mixed Entries\n\nMix strings, glob patterns, and object entries in an array:\n\n```ts\nexport default defineConfig({\n entry: [\n 'src/*',\n '!src/foo.ts',\n { main: 'index.ts' },\n { 'lib/*': ['src/*.ts', '!src/bar.ts'] },\n ],\n})\n```\n\nObject entries take precedence when output names conflict.\n\n### Windows Compatibility\n\nUse forward slashes `/` instead of backslashes `\\` on Windows:\n\n```ts\n// ✅ Correct\nentry: 'src/utils/*.ts'\n\n// ❌ Wrong on Windows\nentry: 'src\\\\utils\\\\*.ts'\n```\n\n## Common Patterns\n\n### Library with Main Export\n\n```ts\nexport default defineConfig({\n entry: 'src/index.ts',\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### Library with Multiple Exports\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n client: 'src/client.ts',\n server: 'src/server.ts',\n },\n format: ['esm', 'cjs'],\n dts: true,\n})\n```\n\n### CLI Tool\n\n```ts\nexport default defineConfig({\n entry: {\n cli: 'src/cli.ts',\n },\n format: ['esm'],\n platform: 'node',\n})\n```\n\n### Preserve Directory Structure\n\nUse with `unbundle: true` to keep file structure:\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n unbundle: true,\n format: ['esm'],\n dts: true,\n})\n```\n\nThis will output files matching the source structure:\n- `src/index.ts` → `dist/index.mjs`\n- `src/utils/helper.ts` → `dist/utils/helper.mjs`\n\n## Tips\n\n1. **Use glob patterns** for multiple related files\n2. **Use object syntax** for custom output names\n3. **Exclude test files** with negation patterns `!**/*.test.ts`\n4. **Combine with unbundle** to preserve directory structure\n5. **Use named entries** for better control over output filenames\n\n\n# Executable - `exe`\n\n**[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html).\n\n## Requirements\n\n- Node.js >= 25.7.0\n- Not supported in Bun or Deno\n\n## Basic Usage\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: true,\n})\n```\n\n## Behavior When Enabled\n\n- Declaration file generation (`dts`) is disabled by default\n- Code splitting is disabled\n- Only single entry points are supported\n- Legacy CJS warnings are suppressed\n\n## Advanced Configuration\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n fileName: 'my-tool',\n seaConfig: {\n disableExperimentalSEAWarning: true,\n useCodeCache: true,\n useSnapshot: false,\n },\n },\n})\n```\n\n## `ExeOptions`\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `seaConfig` | `Omit` | Node.js configuration options |\n| `fileName` | `string \\| ((chunk) => string)` | Custom output file name (without `.exe` or platform suffixes) |\n| `targets` | `ExeTarget[]` | Cross-platform build targets (requires `@tsdown/exe`) |\n\n## `SeaConfig`\n\nSee [Node.js Single Executable Applications documentation](https://nodejs.org/api/single-executable-applications.html).\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `disableExperimentalSEAWarning` | `boolean` | `true` | Disable the experimental warning |\n| `useSnapshot` | `boolean` | `false` | Use V8 snapshot |\n| `useCodeCache` | `boolean` | `false` | Use V8 code cache |\n| `execArgv` | `string[]` | - | Extra Node.js arguments |\n| `execArgvExtension` | `'none' \\| 'env' \\| 'cli'` | `'env'` | How to extend execArgv |\n| `assets` | `Record` | - | Assets to embed |\n\n## Cross-Platform Builds\n\nInstall `@tsdown/exe` to build executables for multiple platforms from a single machine:\n\n```bash\npnpm add -D @tsdown/exe\n```\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [\n { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },\n { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },\n { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },\n ],\n },\n})\n```\n\nThis downloads the target platform's Node.js binary, caches it locally, and produces platform-suffixed output:\n\n```\ndist/\n cli-linux-x64\n cli-darwin-arm64\n cli-win-x64.exe\n```\n\n### `ExeTarget`\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `platform` | `'win' \\| 'darwin' \\| 'linux'` | Target OS (nodejs.org naming) |\n| `arch` | `'x64' \\| 'arm64'` | Target CPU architecture |\n| `nodeVersion` | `string` | Node.js version (must be `>=25.7.0`), or `'latest'` / `'latest-lts'` to resolve automatically |\n\n### Custom Node.js Index and Download URL\n\nWhen downloading Node.js binaries (e.g. behind a corporate proxy or using a mirror), you can customize the sources:\n\n```ts\nexport default defineConfig({\n entry: ['src/cli.ts'],\n exe: {\n targets: [{ platform: 'linux', arch: 'x64', nodeVersion: 'latest-lts' }],\n // Index used to resolve 'latest' / 'latest-lts' versions\n nodeDistIndexUrl: 'https://mirrors.example.com/node/index.json', // default: https://nodejs.org/dist/index.json\n // Fully custom download URL per target\n getDownloadUrl: (target) =>\n `https://mirrors.example.com/node/v${target.nodeVersion}/node-v${target.nodeVersion}-${target.platform}-${target.arch}.tar.gz`,\n },\n})\n```\n\n### Caching\n\nDownloaded Node.js binaries are cached in system cache directories:\n- **macOS:** `~/Library/Caches/tsdown/node/`\n- **Linux:** `~/.cache/tsdown/node/`\n- **Windows:** `%LOCALAPPDATA%/tsdown/Caches/node/`\n\n## Platform Notes\n\n- On macOS, the executable is automatically codesigned (ad-hoc) for Gatekeeper compatibility\n- On Windows, the `.exe` extension is automatically appended\n- When `targets` is specified, `seaConfig.executable` is ignored\n\n## CLI\n\n```bash\ntsdown --exe\ntsdown src/cli.ts --exe\n```\n\n\n# Package Validation (publint & attw)\n\nValidate your package configuration and type declarations before publishing.\n\n## Overview\n\ntsdown integrates with [publint](https://publint.dev/) and [Are the types wrong?](https://arethetypeswrong.github.io/) (attw) to catch common packaging issues. Both are optional dependencies.\n\n## Installation\n\n```bash\n# publint only\nnpm install -D publint\n\n# attw only\nnpm install -D @arethetypeswrong/core\n\n# both\nnpm install -D publint @arethetypeswrong/core\n```\n\n## publint\n\nChecks that `package.json` fields (`exports`, `main`, `module`, `types`) match your actual output files.\n\n### Enable\n\n```ts\nexport default defineConfig({\n publint: true,\n})\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n publint: {\n level: 'error', // 'warning' | 'error' | 'suggestion'\n },\n})\n```\n\n### CLI\n\n```bash\ntsdown --publint\n```\n\n## attw (Are the types wrong?)\n\nVerifies TypeScript declarations are correct across different module resolution strategies (`node10`, `node16`, `bundler`).\n\n### Enable\n\n```ts\nexport default defineConfig({\n attw: true,\n})\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n attw: {\n profile: 'node16', // 'strict' | 'node16' | 'esm-only'\n level: 'error', // 'warn' | 'error'\n ignoreRules: ['false-cjs', 'cjs-resolves-to-esm'],\n },\n})\n```\n\n### Profiles\n\n| Profile | Description |\n|---------|-------------|\n| `strict` | Requires all resolutions to pass (default) |\n| `node16` | Ignores `node10` resolution failures |\n| `esm-only` | Ignores `node10` and `node16-cjs` resolution failures |\n\n### Ignore Rules\n\nSuppress specific problem types with `ignoreRules`:\n\n| Rule | Description |\n|------|-------------|\n| `no-resolution` | Module could not be resolved |\n| `untyped-resolution` | Resolution succeeded but has no types |\n| `false-cjs` | Types indicate CJS but implementation is ESM |\n| `false-esm` | Types indicate ESM but implementation is CJS |\n| `cjs-resolves-to-esm` | CJS resolution points to an ESM module |\n| `fallback-condition` | A fallback/wildcard condition was used |\n| `cjs-only-exports-default` | CJS module only exports a default |\n| `named-exports` | Named exports mismatch between types and implementation |\n| `false-export-default` | Types declare a default export that doesn't exist |\n| `missing-export-equals` | Types are missing `export =` for CJS |\n| `unexpected-module-syntax` | File uses unexpected module syntax |\n| `internal-resolution-error` | Internal resolution error in type checking |\n\n### CLI\n\n```bash\ntsdown --attw\n```\n\n## CI Integration\n\nBoth tools support CI-aware options:\n\n```ts\nexport default defineConfig({\n publint: 'ci-only',\n attw: {\n enabled: 'ci-only',\n profile: 'node16',\n level: 'error',\n },\n})\n```\n\nBoth tools require a `package.json` in your project directory.\n\n## Related Options\n\n- [CI Environment](advanced-ci.md) - CI-aware option details\n- [Package Exports](option-package-exports.md) - Generate exports field\n\n\n# Log Level\n\nControl the verbosity of build output.\n\n## Overview\n\nThe `logLevel` option controls how much information tsdown displays during the build process.\n\n## Type\n\n```ts\nlogLevel?: 'silent' | 'error' | 'warn' | 'info'\n```\n\n**Default:** `'info'`\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Suppress all output\ntsdown --log-level silent\n\n# Only show errors\ntsdown --log-level error\n\n# Show warnings and errors\ntsdown --log-level warn\n\n# Show all info (default)\ntsdown --log-level info\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'error',\n})\n```\n\n## Available Levels\n\n| Level | Shows | Use Case |\n|-------|-------|----------|\n| `silent` | Nothing | CI/CD pipelines, scripting |\n| `error` | Errors only | Minimal output |\n| `warn` | Warnings + errors | Standard CI/CD |\n| `info` | All messages | Development (default) |\n\n## Common Patterns\n\n### CI/CD Pipeline\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'error', // Only show errors in CI\n})\n```\n\n### Scripting\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n logLevel: 'silent', // No output for automation\n})\n```\n\n## Fail on Warnings\n\nThe `failOnWarn` option controls whether warnings cause the build to exit with a non-zero code. Defaults to `false` — warnings never fail the build.\n\n```ts\nexport default defineConfig({\n failOnWarn: false, // Default: never fail on warnings\n // failOnWarn: true, // Always fail on warnings\n // failOnWarn: 'ci-only', // Fail on warnings only in CI\n})\n```\n\nSee [CI Environment](advanced-ci.md) for more about CI-aware options.\n\n## Suppressing Warnings\n\nThe `suppressWarnings` option silences warnings whose message matches a given pattern. This is useful for opting out of non-actionable notices (such as the TypeScript 7.0 experimental API warning) while keeping other warnings visible.\n\n### Type\n\n```ts\nsuppressWarnings?:\n | string\n | RegExp\n | Array\n | ((msg: string) => boolean)\n```\n\n- **string** – substring match\n- **RegExp** – regular expression match\n- **array** – matches if any entry matches\n- **function** – custom predicate\n\n### Usage\n\n```ts\nexport default defineConfig({\n suppressWarnings: [\n 'is experimental', // substring match\n /Circular dependency/, // regexp match\n ],\n // Or a predicate function:\n // suppressWarnings: (msg) => msg.includes('is experimental'),\n})\n```\n\nMatched warnings are dropped **before** `failOnWarn` is applied, so a suppressed warning will not fail the build even when `failOnWarn: true`.\n\n## Related Options\n\n- [CI Environment](advanced-ci.md) - CI-aware option details\n- [CLI Reference](reference-cli.md) - All CLI options\n- [Config File](option-config-file.md) - Configuration setup\n\n\n# Minification\n\nCompress code to reduce bundle size.\n\n## Overview\n\nMinification removes unnecessary characters (whitespace, comments) and optimizes code for production, reducing bundle size and improving load times.\n\n**Note:** Uses [Oxc minifier](https://oxc.rs/docs/contribute/minifier) internally. The minifier is currently in alpha.\n\n## Type\n\n```ts\nminify?: boolean | 'dce-only' | MinifyOptions\n```\n\n- `true` — Enable full minification (whitespace removal, mangling, compression)\n- `false` — Disable minification (default)\n- `'dce-only'` — Only perform dead code elimination without full minification\n- `MinifyOptions` — Pass detailed options to the Oxc minifier\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Enable minification\ntsdown --minify\n\n# Disable minification\ntsdown --no-minify\n```\n\n**Note:** The CLI `--minify` flag is a boolean toggle. For `'dce-only'` mode or advanced options, use the config file.\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n minify: true,\n})\n```\n\n### DCE-Only Mode\n\nRemove dead code without full minification (keeps readable output):\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n minify: 'dce-only',\n})\n```\n\n## Example Output\n\n### Without Minification\n\n```js\n// dist/index.mjs\nconst x = 1\n\nfunction hello(x$1) {\n console.log('Hello World')\n console.log(x$1)\n}\n\nhello(x)\n```\n\n### With Minification\n\n```js\n// dist/index.mjs\nconst e=1;function t(e){console.log(`Hello World`),console.log(e)}t(e);\n```\n\n## Common Patterns\n\n### Production Build\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n minify: true,\n clean: true,\n})\n```\n\n### Conditional Minification\n\n```ts\nexport default defineConfig((options) => ({\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: !options.watch, // Only minify in production\n}))\n```\n\n### Browser Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['iife'],\n platform: 'browser',\n globalName: 'MyLib',\n minify: true,\n})\n```\n\n### Multiple Builds\n\n```ts\nexport default defineConfig([\n // Development build\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: false,\n outDir: 'dist/dev',\n },\n // Production build\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n minify: true,\n outDir: 'dist/prod',\n },\n])\n```\n\n## CLI Examples\n\n```bash\n# Production build with minification\ntsdown --minify --clean\n\n# Multiple formats with minification\ntsdown --format esm --format cjs --minify\n\n# Conditional minification (only when not watching)\ntsdown --minify # Or omit --watch\n```\n\n## Tips\n\n1. **Use `minify: true`** for production builds\n2. **Use `'dce-only'`** to remove dead code while keeping output readable\n3. **Skip minification** during development for faster rebuilds\n4. **Combine with tree shaking** for best results\n5. **Test minified output** thoroughly (Oxc minifier is in alpha)\n\n## Troubleshooting\n\n### Minified Code Has Bugs\n\nOxc minifier is in alpha and may have issues:\n\n1. **Use DCE-only mode**: `minify: 'dce-only'`\n2. **Report bug** to [Oxc project](https://github.com/oxc-project/oxc/issues)\n3. **Disable minification**: `minify: false`\n\n### Unexpected Output\n\n- **Test unminified** first to isolate issue\n- **Check source maps** for debugging\n- **Verify target compatibility**\n\n## Related Options\n\n- [Tree Shaking](option-tree-shaking.md) - Remove unused code\n- [Target](option-target.md) - Syntax transformations\n- [Output Format](option-output-format.md) - Module formats\n- [Sourcemap](option-sourcemap.md) - Debug information\n\n\n# Output Directory\n\nConfigure the output directory for bundled files.\n\n## Overview\n\nBy default, tsdown outputs bundled files to the `dist` directory. You can customize this location using the `outDir` option.\n\n## Basic Usage\n\n### CLI\n\n```bash\n# Default output to dist/\ntsdown\n\n# Custom output directory\ntsdown --out-dir build\ntsdown -d lib\n```\n\n### Config File\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: 'build',\n})\n```\n\n## Common Patterns\n\n### Standard Library\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist', // Default\n dts: true,\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n├── index.cjs\n└── index.d.ts\n```\n\n### Separate Directories by Format\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm'],\n outDir: 'dist/esm',\n },\n {\n entry: ['src/index.ts'],\n format: ['cjs'],\n outDir: 'dist/cjs',\n },\n])\n```\n\n**Output:**\n```\ndist/\n├── esm/\n│ └── index.js\n└── cjs/\n └── index.js\n```\n\n### Monorepo Package\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: 'lib', // Custom directory\n clean: true,\n})\n```\n\n### Build to Root\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n outDir: '.', // Output to project root (not recommended)\n clean: false, // Don't clean root!\n})\n```\n\n**Warning:** Be careful when outputting to root to avoid deleting important files.\n\n## Output Extensions\n\n### Custom Extensions\n\nUse `outExtensions` to control file extensions:\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist',\n outExtensions({ format }) {\n return {\n js: format === 'esm' ? '.mjs' : '.cjs',\n }\n },\n})\n```\n\n### Default Extensions\n\n| Format | Default Extension | With `type: \"module\"` |\n|--------|-------------------|----------------------|\n| `esm` | `.mjs` | `.js` |\n| `cjs` | `.cjs` | `.js` |\n| `iife` | `.iife.js` | `.iife.js` |\n| `umd` | `.umd.js` | `.umd.js` |\n\nFor IIFE/UMD builds, `outExtensions` customizes extensions or suffixes but does not remove the built-in `.iife` or `.umd` segment. Use `outputOptions.entryFileNames` for custom full filename patterns.\n\n### ESM with .js Extension\n\n```ts\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['esm'],\n outExtensions: () => ({ js: '.js' }),\n})\n```\n\nRequires `\"type\": \"module\"` in package.json.\n\n## File Naming\n\n### Entry Names\n\nControl output filenames based on entry names:\n\n```ts\nexport default defineConfig({\n entry: {\n index: 'src/index.ts',\n utils: 'src/utils.ts',\n },\n outDir: 'dist',\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n└── utils.mjs\n```\n\n### Glob Entry\n\n```ts\nexport default defineConfig({\n entry: ['src/**/*.ts', '!**/*.test.ts'],\n outDir: 'dist',\n unbundle: true, // Preserve structure\n})\n```\n\n**Output:**\n```\ndist/\n├── index.mjs\n├── utils/\n│ └── helper.mjs\n└── components/\n └── button.mjs\n```\n\n## Multiple Builds\n\n### Same Output Directory\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n outDir: 'dist',\n clean: true, // Clean first\n },\n {\n entry: ['src/cli.ts'],\n outDir: 'dist',\n clean: false, // Don't clean again\n },\n])\n```\n\n### Different Output Directories\n\n```ts\nexport default defineConfig([\n {\n entry: ['src/index.ts'],\n format: ['esm', 'cjs'],\n outDir: 'dist/lib',\n },\n {\n entry: ['src/cli.ts'],\n format: ['esm'],\n outDir: 'dist/bin',\n },\n])\n```\n\n## CLI Examples\n\n```bash\n# Default\ntsdown\n\n# Custom directory\ntsdown --out-dir build\ntsdown -d lib\n\n# Nested directory\ntsdown --out-dir dist/lib\n\n# With other options\ntsdown --out-dir build --format esm,cjs --dts\n```\n\n## Tips\n\n1. **Use default `dist`** for standard projects\n2. **Be careful with root** - avoid `outDir: '.'`\n3. **Clean before build** - use `clean: true`\n4. **Consistent naming** - match your project conventions\n5. **Separate by format** if needed for clarity\n6. **Check .gitignore** - ensure output dir is ignored\n\n## Troubleshooting\n\n### Files Not in Expected Location\n\n- Check `outDir` config\n- Verify build completed successfully\n- Look for typos in path\n\n### Files Deleted Unexpectedly\n\n- Check if `clean: true`\n- Ensure outDir doesn't overlap with source\n- Don't use root as outDir\n\n### Permission Errors\n\n- Check write permissions\n- Ensure directory isn't locked\n- Try different location\n\n## Related Options\n\n- [Cleaning](option-cleaning.md) - Clean output directory\n- [Entry](option-entry.md) - Entry points\n- [Output Format](option-output-format.md) - Module formats\n- [Unbundle](option-unbundle.md) - Preserve structure\n\n\n# Output Format\n\nConfigure the module format(s) for generated bundles.\n\n## Overview\n\ntsdown can generate bundles in multiple formats. Default is ESM.\n\n## Available Formats\n\n| Format | Description | Use Case |\n|--------|-------------|----------|\n| `esm` | ECMAScript Module (default) | Modern Node.js, browsers, Deno |\n| `cjs` | CommonJS | Legacy Node.js, require() |\n| `iife` | Immediately Invoked Function Expression | Browser `