devskill 2.0.2

package/skills/tsdown/references/guide-migrate-from-tsup.md

@@ -0,0 +1,189 @@
+# Migrate from tsup
+
+Migration guide for switching from tsup to tsdown.
+
+## Overview
+
+tsdown is built on Rolldown (Rust-based) vs tsup's esbuild, providing faster and more powerful bundling while maintaining compatibility.
+
+## Automatic Migration
+
+### Single Package
+
+```bash
+npx tsdown-migrate
+```
+
+### Monorepo
+
+```bash
+# Using glob patterns
+npx tsdown-migrate packages/*
+
+# Multiple directories
+npx tsdown-migrate packages/foo packages/bar
+```
+
+### Migration Options
+
+- `[...dirs]` - Directories to migrate (supports globs)
+- `--dry-run` or `-d` - Preview changes without modifying files
+
+**Important:** Commit your changes before running migration.
+
+## Key Differences
+
+### Default Values
+
+| Option | tsup | tsdown |
+|--------|------|--------|
+| `format` | `['cjs']` | `['esm']` |
+| `clean` | `false` | `true` |
+| `dts` | `false` | Auto-enabled if `types`/`typings` in package.json |
+| `target` | Manual | Auto-read from `engines.node` in package.json |
+
+### New Features in tsdown
+
+#### Node Protocol Control
+
+```ts
+export default defineConfig({
+  nodeProtocol: true,      // Add node: prefix (fs → node:fs)
+  nodeProtocol: 'strip',   // Remove node: prefix (node:fs → fs)
+  nodeProtocol: false,     // Keep as-is (default)
+})
+```
+
+#### Better Workspace Support
+
+```ts
+export default defineConfig({
+  workspace: 'packages/*',  // Build all packages
+})
+```
+
+## Migration Checklist
+
+1. **Backup your code** - Commit all changes
+2. **Run migration tool** - `npx tsdown-migrate`
+3. **Review changes** - Check modified config files
+4. **Update scripts** - Change `tsup` to `tsdown` in package.json
+5. **Test build** - Run `pnpm build` to verify
+6. **Adjust config** - Fine-tune based on your needs
+
+## Common Migration Patterns
+
+### Basic Library
+
+**Before (tsup):**
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+})
+```
+
+**After (tsdown):**
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],  // ESM now default
+  dts: true,
+  clean: true,  // Now enabled by default
+})
+```
+
+### With Custom Target
+
+**Before (tsup):**
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  target: 'es2020',
+})
+```
+
+**After (tsdown):**
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  // target auto-reads from package.json engines.node
+  // Or override explicitly:
+  target: 'es2020',
+})
+```
+
+### CLI Scripts
+
+**Before (package.json):**
+```json
+{
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}
+```
+
+**After (package.json):**
+```json
+{
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch"
+  }
+}
+```
+
+## Feature Compatibility
+
+### Supported tsup Features
+
+Most tsup features are supported:
+- ✅ Multiple entry points
+- ✅ Multiple formats (ESM, CJS, IIFE, UMD)
+- ✅ TypeScript declarations
+- ✅ Source maps
+- ✅ Minification
+- ✅ Watch mode
+- ✅ External dependencies
+- ✅ Tree shaking
+- ✅ Shims
+- ✅ Plugins (Rollup compatible)
+
+### Missing Features
+
+Some tsup features are not yet available. Check [GitHub issues](https://github.com/rolldown/tsdown/issues) for status and request features.
+
+## Troubleshooting
+
+### Build Fails After Migration
+
+1. **Check Node.js version** - Requires Node.js 20.19+
+2. **Install TypeScript** - Required for DTS generation
+3. **Review config changes** - Ensure format and options are correct
+4. **Check dependencies** - Verify all dependencies are installed
+
+### Different Output
+
+- **Format order** - tsdown defaults to ESM first
+- **Clean behavior** - tsdown cleans outDir by default
+- **Target** - tsdown auto-detects from package.json
+
+### Performance Issues
+
+tsdown should be faster than tsup. If not:
+1. Enable `isolatedDeclarations` for faster DTS generation
+2. Check for large dependencies being bundled
+3. Use `skipNodeModulesBundle` if needed
+
+## Getting Help
+
+- [GitHub Issues](https://github.com/rolldown/tsdown/issues) - Report bugs or request features
+- [Documentation](https://tsdown.dev) - Full documentation
+- [Migration Tool](https://github.com/rolldown/tsdown/tree/main/packages/tsdown-migrate) - Source code
+
+## Acknowledgements
+
+tsdown is heavily inspired by tsup and incorporates parts of its codebase. Thanks to [@egoist](https://github.com/egoist) and the tsup community.

package/skills/tsdown/references/option-cjs-default.md

@@ -0,0 +1,98 @@
+# CJS Default Export
+
+Control how default exports are handled in CommonJS output.
+
+## Overview
+
+The `cjsDefault` option improves compatibility when generating CommonJS modules. When enabled (default), modules with only a single default export use `module.exports = ...` instead of `exports.default = ...`.
+
+## Type
+
+```ts
+cjsDefault?: boolean  // default: true
+```
+
+## Basic Usage
+
+### Enabled (Default)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs'],
+  cjsDefault: true,  // default behavior
+})
+```
+
+### Disabled
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs'],
+  cjsDefault: false,
+})
+```
+
+## How It Works
+
+### With `cjsDefault: true` (Default)
+
+When your module has **only a single default export**, tsdown transforms:
+
+**Source:**
+```ts
+// src/index.ts
+export default function greet() {
+  console.log('Hello, world!')
+}
+```
+
+**Generated CJS:**
+```js
+// dist/index.cjs
+function greet() {
+  console.log('Hello, world!')
+}
+module.exports = greet
+```
+
+**Generated Declaration:**
+```ts
+// dist/index.d.cts
+declare function greet(): void
+export = greet
+```
+
+This allows consumers to use `const greet = require('your-module')` directly.
+
+### With `cjsDefault: false`
+
+The default export stays as `exports.default`:
+
+```js
+// dist/index.cjs
+function greet() {
+  console.log('Hello, world!')
+}
+exports.default = greet
+```
+
+Consumers need `require('your-module').default`.
+
+## When to Disable
+
+- When your module has both default and named exports
+- When you need consistent `exports.default` behavior
+- When consumers always use ESM imports
+
+## Tips
+
+1. **Leave enabled** for most libraries (default `true`)
+2. **Disable** if you have both default and named exports and need consistent behavior
+3. **Test CJS consumers** to verify compatibility
+
+## Related Options
+
+- [Output Format](option-output-format.md) - Module formats
+- [Shims](option-shims.md) - ESM/CJS compatibility

package/skills/tsdown/references/option-cleaning.md

@@ -0,0 +1,275 @@
+# Output Directory Cleaning
+
+Control how the output directory is cleaned before builds.
+
+## Overview
+
+By default, tsdown **cleans the output directory** before each build to remove stale files from previous builds.
+
+## Basic Usage
+
+### CLI
+
+```bash
+# Clean enabled (default)
+tsdown
+
+# Disable cleaning
+tsdown --no-clean
+```
+
+### Config File
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  clean: true,  // Default
+})
+```
+
+## Behavior
+
+### With Cleaning (Default)
+
+Before each build:
+1. All files in `outDir` are removed
+2. Fresh build starts with empty directory
+3. Only current build outputs remain
+
+**Benefits:**
+- No stale files
+- Predictable output
+- Clean slate each build
+
+### Without Cleaning
+
+Build outputs are added to existing files:
+
+```ts
+export default defineConfig({
+  clean: false,
+})
+```
+
+**Use when:**
+- Multiple builds to same directory
+- Incremental builds
+- Preserving other files
+- Watch mode (faster rebuilds)
+
+## Common Patterns
+
+### Production Build
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  clean: true,  // Ensure clean output
+  minify: true,
+})
+```
+
+### Development Mode
+
+```ts
+export default defineConfig((options) => ({
+  entry: ['src/index.ts'],
+  clean: !options.watch,  // Don't clean in watch mode
+  sourcemap: options.watch,
+}))
+```
+
+### Multiple Builds
+
+```ts
+export default defineConfig([
+  {
+    entry: ['src/index.ts'],
+    outDir: 'dist',
+    clean: true,  // Clean once
+  },
+  {
+    entry: ['src/cli.ts'],
+    outDir: 'dist',
+    clean: false,  // Don't clean, add to same dir
+  },
+])
+```
+
+### Monorepo Package
+
+```ts
+export default defineConfig({
+  workspace: 'packages/*',
+  entry: ['src/index.ts'],
+  clean: true,  // Clean each package's dist
+})
+```
+
+### Preserve Static Files
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  clean: false,  // Keep manually added files
+  outDir: 'dist',
+})
+
+// Manually copy files first
+// Then run tsdown --no-clean
+```
+
+## Clean Patterns
+
+### Selective Cleaning
+
+```ts
+import { rmSync } from 'fs'
+
+export default defineConfig({
+  clean: false,  // Disable auto clean
+  hooks: {
+    'build:prepare': () => {
+      // Custom cleaning logic
+      rmSync('dist/*.js', { force: true })
+      // Keep other files
+    },
+  },
+})
+```
+
+### Clean Specific Directories
+
+```ts
+export default defineConfig({
+  clean: false,
+  hooks: {
+    'build:prepare': async () => {
+      const { rm } = await import('fs/promises')
+      // Only clean specific subdirectories
+      await rm('dist/esm', { recursive: true, force: true })
+      await rm('dist/cjs', { recursive: true, force: true })
+      // Keep dist/types
+    },
+  },
+})
+```
+
+## Watch Mode Behavior
+
+In watch mode, cleaning behavior is important:
+
+### Clean on First Build Only
+
+```ts
+export default defineConfig((options) => ({
+  entry: ['src/index.ts'],
+  watch: options.watch,
+  clean: !options.watch,  // Only clean initial build
+}))
+```
+
+**Result:**
+- First build: Clean
+- Subsequent rebuilds: Incremental
+
+### Always Clean
+
+```ts
+export default defineConfig({
+  watch: true,
+  clean: true,  // Clean every rebuild
+})
+```
+
+**Trade-off:** Slower rebuilds, but always fresh output.
+
+## Tips
+
+1. **Leave enabled** for production builds
+2. **Disable in watch mode** for faster rebuilds
+3. **Use multiple configs** carefully with cleaning
+4. **Custom clean logic** via hooks if needed
+5. **Be cautious** - cleaning removes ALL files in outDir
+6. **Test cleaning** - ensure no important files are lost
+
+## Troubleshooting
+
+### Important Files Deleted
+
+- Don't put non-build files in outDir
+- Use separate directory for static files
+- Disable cleaning and manage manually
+
+### Stale Files in Output
+
+- Enable cleaning: `clean: true`
+- Or manually remove before build
+
+### Slow Rebuilds in Watch
+
+- Disable cleaning in watch mode
+- Use incremental builds
+
+## CLI Examples
+
+```bash
+# Default (clean enabled)
+tsdown
+
+# Disable cleaning
+tsdown --no-clean
+
+# Watch mode without cleaning
+tsdown --watch --no-clean
+
+# Multiple formats with cleaning
+tsdown --format esm,cjs --clean
+```
+
+## Examples
+
+### Safe Production Build
+
+```bash
+# Clean before build
+rm -rf dist
+tsdown --clean
+```
+
+### Incremental Development
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  watch: true,
+  clean: false,  // Faster rebuilds
+  sourcemap: true,
+})
+```
+
+### Multi-Stage Build
+
+```ts
+// Stage 1: Clean and build main
+export default defineConfig([
+  {
+    entry: ['src/index.ts'],
+    outDir: 'dist',
+    clean: true,
+  },
+  {
+    entry: ['src/utils.ts'],
+    outDir: 'dist',
+    clean: false,  // Add to same directory
+  },
+])
+```
+
+## Related Options
+
+- [Output Directory](option-output-directory.md) - Configure outDir
+- [Watch Mode](option-watch-mode.md) - Development workflow
+- [Hooks](advanced-hooks.md) - Custom clean logic
+- [Entry](option-entry.md) - Entry points