devskill 2.0.2

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

@@ -0,0 +1,310 @@
+# Unbundle Mode
+
+Preserve source directory structure in output.
+
+## Overview
+
+Unbundle mode (also called "bundleless" or "transpile-only") outputs files that mirror your source structure, rather than bundling everything into single files. Each source file is compiled individually with a one-to-one mapping.
+
+## Basic Usage
+
+### CLI
+
+```bash
+tsdown --unbundle
+```
+
+### Config File
+
+```ts
+export default defineConfig({
+  entry: ['src/**/*.ts', '!**/*.test.ts'],
+  unbundle: true,
+})
+```
+
+## How It Works
+
+### Source Structure
+
+```
+src/
+├── index.ts
+├── utils/
+│   ├── helper.ts
+│   └── format.ts
+└── components/
+    └── button.ts
+```
+
+### With Unbundle
+
+**Config:**
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  unbundle: true,
+})
+```
+
+**Output:**
+```
+dist/
+├── index.mjs
+├── utils/
+│   ├── helper.mjs
+│   └── format.mjs
+└── components/
+    └── button.mjs
+```
+
+All imported files are output individually, preserving structure.
+
+### Without Unbundle (Default)
+
+**Output:**
+```
+dist/
+└── index.mjs  (all code bundled together)
+```
+
+## When to Use
+
+### Use Unbundle When:
+
+✅ Building monorepo packages with shared utilities
+✅ Users need to import individual modules
+✅ Want clear source-to-output mapping
+✅ Library with many independent utilities
+✅ Debugging requires tracing specific files
+✅ Incremental builds for faster development
+
+### Use Standard Bundling When:
+
+❌ Single entry point application
+❌ Want to optimize bundle size
+❌ Need aggressive tree shaking
+❌ Creating IIFE/UMD bundles
+❌ Deploying to browsers directly
+
+## Common Patterns
+
+### Utility Library
+
+```ts
+export default defineConfig({
+  entry: ['src/**/*.ts', '!**/*.test.ts'],
+  format: ['esm', 'cjs'],
+  unbundle: true,
+  dts: true,
+})
+```
+
+**Benefits:**
+- Users import only what they need
+- Tree shaking still works at user's build
+- Clear module boundaries
+
+**Usage:**
+```ts
+// Users can import specific utilities
+import { helper } from 'my-lib/utils/helper'
+import { Button } from 'my-lib/components/button'
+```
+
+### Monorepo Shared Package
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  unbundle: true,
+  outDir: 'dist',
+})
+```
+
+### TypeScript Compilation Only
+
+```ts
+export default defineConfig({
+  entry: ['src/**/*.ts'],
+  format: ['esm'],
+  unbundle: true,
+  minify: false,
+  treeshake: false,
+  dts: true,
+})
+```
+
+Pure TypeScript to JavaScript transformation.
+
+### Development Mode
+
+```ts
+export default defineConfig((options) => ({
+  entry: ['src/**/*.ts'],
+  unbundle: options.watch,  // Unbundle in dev only
+  minify: !options.watch,
+}))
+```
+
+Fast rebuilds during development, optimized for production.
+
+## With Entry Patterns
+
+### Include/Exclude
+
+```ts
+export default defineConfig({
+  entry: [
+    'src/**/*.ts',
+    '!**/*.test.ts',
+    '!**/*.spec.ts',
+    '!**/fixtures/**',
+  ],
+  unbundle: true,
+})
+```
+
+### Multiple Entry Points
+
+```ts
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    cli: 'src/cli.ts',
+  },
+  unbundle: true,
+})
+```
+
+Both entry files and all imports preserved.
+
+## Output Control
+
+### Custom Extension
+
+```ts
+export default defineConfig({
+  entry: ['src/**/*.ts'],
+  unbundle: true,
+  outExtensions: () => ({ js: '.js' }),
+})
+```
+
+### Preserve Directory
+
+```ts
+export default defineConfig({
+  entry: ['src/**/*.ts'],
+  unbundle: true,
+  outDir: 'lib',
+})
+```
+
+**Output:**
+```
+lib/
+├── index.js
+├── utils/
+│   └── helper.js
+└── components/
+    └── button.js
+```
+
+## Package.json Setup
+
+```json
+{
+  "name": "my-library",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./utils/*": "./dist/utils/*.js",
+    "./components/*": "./dist/components/*.js"
+  },
+  "files": ["dist"]
+}
+```
+
+Or use `exports: true` to auto-generate.
+
+## Comparison
+
+| Feature | Bundled | Unbundled |
+|---------|---------|-----------|
+| Output files | Few | Many |
+| File size | Smaller | Larger |
+| Build speed | Slower | Faster |
+| Tree shaking | Build time | User's build |
+| Source mapping | Complex | Simple |
+| Module imports | Entry only | Any module |
+| Dev rebuilds | Slower | Faster |
+
+## Performance
+
+### Build Speed
+
+Unbundle is typically faster:
+- No bundling overhead
+- Parallel file processing
+- Incremental builds possible
+
+### Bundle Size
+
+Unbundle produces larger output:
+- Each file has its own overhead
+- No cross-module optimizations
+- User's bundler handles final optimization
+
+## Tips
+
+1. **Use with glob patterns** for multiple files
+2. **Enable in development** for faster rebuilds
+3. **Let users bundle** for production optimization
+4. **Preserve structure** for utilities/components
+5. **Combine with DTS** for type definitions
+6. **Use with monorepos** for shared code
+
+## Troubleshooting
+
+### Too Many Files
+
+- Adjust entry patterns
+- Exclude unnecessary files
+- Use specific entry points
+
+### Missing Files
+
+- Check entry patterns
+- Verify files are imported
+- Look for excluded patterns
+
+### Import Paths Wrong
+
+- Check relative paths
+- Verify output structure
+- Update package.json exports
+
+## CLI Examples
+
+```bash
+# Enable unbundle
+tsdown --unbundle
+
+# With specific entry
+tsdown src/**/*.ts --unbundle
+
+# With other options
+tsdown --unbundle --format esm --dts
+```
+
+## Related Options
+
+- [Root Directory](option-root.md) - Control output directory mapping
+- [Entry](option-entry.md) - Entry patterns
+- [Output Directory](option-output-directory.md) - Output location
+- [Output Format](option-output-format.md) - Module formats
+- [DTS](option-dts.md) - Type declarations

package/skills/tsdown/references/option-watch-mode.md

@@ -0,0 +1,261 @@
+# Watch Mode
+
+Automatically rebuild when files change.
+
+## Overview
+
+Watch mode monitors your source files and rebuilds automatically on changes, streamlining the development workflow.
+
+## Basic Usage
+
+### CLI
+
+```bash
+# Watch all project files
+tsdown --watch
+
+# Or use short flag
+tsdown -w
+
+# Watch specific directory
+tsdown --watch ./src
+
+# Watch specific file
+tsdown --watch ./src/index.ts
+```
+
+### Config File
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  watch: true,
+})
+```
+
+## Watch Options
+
+### Ignore Paths
+
+Ignore specific paths in watch mode:
+
+```bash
+tsdown --watch --ignore-watch test --ignore-watch '**/*.test.ts'
+```
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  watch: {
+    exclude: ['test/**', '**/*.test.ts'],
+  },
+})
+```
+
+### On Success Command
+
+Run command after successful build:
+
+```bash
+tsdown --watch --on-success "echo Build complete!"
+tsdown --watch --on-success "node dist/index.mjs"
+```
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  watch: true,
+  onSuccess: 'node dist/index.mjs',
+})
+```
+
+## Watch Behavior
+
+### Default Watch Targets
+
+By default, tsdown watches:
+- All entry files
+- All imported files
+- Config file (triggers restart)
+
+### File Change Handling
+
+- **Source files** - Incremental rebuild
+- **Config file** - Full restart with cache clear
+- **Dependencies** - Rebuild if imported
+
+### Keyboard Shortcuts
+
+During watch mode:
+- `r` - Manual rebuild
+- `q` - Quit watch mode
+
+## Common Patterns
+
+### Development Mode
+
+```ts
+export default defineConfig((options) => ({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  watch: options.watch,
+  sourcemap: options.watch,
+  minify: !options.watch,
+}))
+```
+
+### With Post-Build Script
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  watch: true,
+  onSuccess: 'npm run test',
+})
+```
+
+### Multiple Entry Points
+
+```ts
+export default defineConfig({
+  entry: {
+    main: 'src/index.ts',
+    cli: 'src/cli.ts',
+  },
+  watch: true,
+  clean: false,  // Don't clean on each rebuild
+})
+```
+
+### Test Runner Integration
+
+```bash
+# Watch and run tests on change
+tsdown --watch --on-success "vitest run"
+
+# Watch and start dev server
+tsdown --watch --on-success "node dist/server.mjs"
+```
+
+### Monorepo Package
+
+```ts
+export default defineConfig({
+  workspace: 'packages/*',
+  entry: ['src/index.ts'],
+  watch: true,
+  watch: {
+    exclude: ['**/test/**', '**/*.spec.ts'],
+  },
+})
+```
+
+## Advanced Configuration
+
+### Custom Watch Options
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  watch: {
+    include: ['src/**'],
+    exclude: ['**/*.test.ts', '**/fixtures/**'],
+    skipWrite: false,
+  },
+})
+```
+
+### Conditional Watch
+
+```ts
+export default defineConfig((options) => {
+  const isDev = options.watch
+
+  return {
+    entry: ['src/index.ts'],
+    format: ['esm'],
+    dts: !isDev,        // Skip DTS in watch mode
+    sourcemap: isDev,
+    clean: !isDev,
+  }
+})
+```
+
+## CLI Examples
+
+```bash
+# Basic watch
+tsdown -w
+
+# Watch with source maps
+tsdown -w --sourcemap
+
+# Watch without cleaning
+tsdown -w --no-clean
+
+# Watch and run on success
+tsdown -w --on-success "npm test"
+
+# Watch specific format
+tsdown -w --format esm
+
+# Watch with minification
+tsdown -w --minify
+
+# Watch and ignore test files
+tsdown -w --ignore-watch '**/*.test.ts'
+```
+
+## Tips
+
+1. **Use watch mode** for active development
+2. **Skip DTS generation** in watch for faster rebuilds
+3. **Disable clean** to avoid unnecessary file operations
+4. **Use onSuccess** for post-build tasks
+5. **Ignore test files** to avoid unnecessary rebuilds
+6. **Use keyboard shortcuts** for manual control
+
+## Troubleshooting
+
+### Watch Not Detecting Changes
+
+- Check file is in entry or imported chain
+- Verify path is not in `exclude` patterns
+- Ensure file system supports watching
+
+### Too Many Rebuilds
+
+Add ignore patterns:
+
+```ts
+export default defineConfig({
+  watch: {
+    exclude: [
+      '**/node_modules/**',
+      '**/.git/**',
+      '**/dist/**',
+      '**/*.test.ts',
+    ],
+  },
+})
+```
+
+### Slow Rebuilds
+
+- Skip DTS in watch mode: `dts: !options.watch`
+- Disable minification: `minify: false`
+- Use smaller entry set during development
+
+### Config Changes Not Applied
+
+Config file changes trigger full restart automatically.
+
+### Why Not Stub Mode?
+
+tsdown does not support stub mode. Watch mode is the recommended alternative for rapid development, providing instant rebuilds without the drawbacks of stub mode.
+
+## Related Options
+
+- [On Success](reference-cli.md#on-success-command) - Post-build commands
+- [Sourcemap](option-sourcemap.md) - Debug information
+- [Clean](option-cleaning.md) - Output directory cleaning