devskill 2.0.2

package/skills/tsdown/references/option-output-directory.md

@@ -0,0 +1,270 @@
+# Output Directory
+
+Configure the output directory for bundled files.
+
+## Overview
+
+By default, tsdown outputs bundled files to the `dist` directory. You can customize this location using the `outDir` option.
+
+## Basic Usage
+
+### CLI
+
+```bash
+# Default output to dist/
+tsdown
+
+# Custom output directory
+tsdown --out-dir build
+tsdown -d lib
+```
+
+### Config File
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  outDir: 'build',
+})
+```
+
+## Common Patterns
+
+### Standard Library
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  outDir: 'dist',  // Default
+  dts: true,
+})
+```
+
+**Output:**
+```
+dist/
+├── index.mjs
+├── index.cjs
+└── index.d.ts
+```
+
+### Separate Directories by Format
+
+```ts
+export default defineConfig([
+  {
+    entry: ['src/index.ts'],
+    format: ['esm'],
+    outDir: 'dist/esm',
+  },
+  {
+    entry: ['src/index.ts'],
+    format: ['cjs'],
+    outDir: 'dist/cjs',
+  },
+])
+```
+
+**Output:**
+```
+dist/
+├── esm/
+│   └── index.js
+└── cjs/
+    └── index.js
+```
+
+### Monorepo Package
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  outDir: 'lib',  // Custom directory
+  clean: true,
+})
+```
+
+### Build to Root
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  outDir: '.',  // Output to project root (not recommended)
+  clean: false,  // Don't clean root!
+})
+```
+
+**Warning:** Be careful when outputting to root to avoid deleting important files.
+
+## Output Extensions
+
+### Custom Extensions
+
+Use `outExtensions` to control file extensions:
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  outDir: 'dist',
+  outExtensions({ format }) {
+    return {
+      js: format === 'esm' ? '.mjs' : '.cjs',
+    }
+  },
+})
+```
+
+### Default Extensions
+
+| Format | Default Extension | With `type: "module"` |
+|--------|-------------------|----------------------|
+| `esm` | `.mjs` | `.js` |
+| `cjs` | `.cjs` | `.js` |
+| `iife` | `.global.js` | `.global.js` |
+| `umd` | `.umd.js` | `.umd.js` |
+
+### ESM with .js Extension
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  outExtensions: () => ({ js: '.js' }),
+})
+```
+
+Requires `"type": "module"` in package.json.
+
+## File Naming
+
+### Entry Names
+
+Control output filenames based on entry names:
+
+```ts
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    utils: 'src/utils.ts',
+  },
+  outDir: 'dist',
+})
+```
+
+**Output:**
+```
+dist/
+├── index.mjs
+└── utils.mjs
+```
+
+### Glob Entry
+
+```ts
+export default defineConfig({
+  entry: ['src/**/*.ts', '!**/*.test.ts'],
+  outDir: 'dist',
+  unbundle: true,  // Preserve structure
+})
+```
+
+**Output:**
+```
+dist/
+├── index.mjs
+├── utils/
+│   └── helper.mjs
+└── components/
+    └── button.mjs
+```
+
+## Multiple Builds
+
+### Same Output Directory
+
+```ts
+export default defineConfig([
+  {
+    entry: ['src/index.ts'],
+    outDir: 'dist',
+    clean: true,  // Clean first
+  },
+  {
+    entry: ['src/cli.ts'],
+    outDir: 'dist',
+    clean: false,  // Don't clean again
+  },
+])
+```
+
+### Different Output Directories
+
+```ts
+export default defineConfig([
+  {
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs'],
+    outDir: 'dist/lib',
+  },
+  {
+    entry: ['src/cli.ts'],
+    format: ['esm'],
+    outDir: 'dist/bin',
+  },
+])
+```
+
+## CLI Examples
+
+```bash
+# Default
+tsdown
+
+# Custom directory
+tsdown --out-dir build
+tsdown -d lib
+
+# Nested directory
+tsdown --out-dir dist/lib
+
+# With other options
+tsdown --out-dir build --format esm,cjs --dts
+```
+
+## Tips
+
+1. **Use default `dist`** for standard projects
+2. **Be careful with root** - avoid `outDir: '.'`
+3. **Clean before build** - use `clean: true`
+4. **Consistent naming** - match your project conventions
+5. **Separate by format** if needed for clarity
+6. **Check .gitignore** - ensure output dir is ignored
+
+## Troubleshooting
+
+### Files Not in Expected Location
+
+- Check `outDir` config
+- Verify build completed successfully
+- Look for typos in path
+
+### Files Deleted Unexpectedly
+
+- Check if `clean: true`
+- Ensure outDir doesn't overlap with source
+- Don't use root as outDir
+
+### Permission Errors
+
+- Check write permissions
+- Ensure directory isn't locked
+- Try different location
+
+## Related Options
+
+- [Cleaning](option-cleaning.md) - Clean output directory
+- [Entry](option-entry.md) - Entry points
+- [Output Format](option-output-format.md) - Module formats
+- [Unbundle](option-unbundle.md) - Preserve structure

package/skills/tsdown/references/option-output-format.md

@@ -0,0 +1,181 @@
+# Output Format
+
+Configure the module format(s) for generated bundles.
+
+## Overview
+
+tsdown can generate bundles in multiple formats. Default is ESM.
+
+## Available Formats
+
+| Format | Description | Use Case |
+|--------|-------------|----------|
+| `esm` | ECMAScript Module (default) | Modern Node.js, browsers, Deno |
+| `cjs` | CommonJS | Legacy Node.js, require() |
+| `iife` | Immediately Invoked Function Expression | Browser `<script>` tags |
+| `umd` | Universal Module Definition | AMD, CommonJS, and globals |
+
+## Usage
+
+### CLI
+
+```bash
+# Single format
+tsdown --format esm
+
+# Multiple formats
+tsdown --format esm --format cjs
+
+# Or comma-separated
+tsdown --format esm,cjs
+```
+
+### Config File
+
+#### Single Format
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: 'esm',
+})
+```
+
+#### Multiple Formats
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+})
+```
+
+## Per-Format Configuration
+
+Override options for specific formats:
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: {
+    esm: {
+      target: ['es2015'],
+    },
+    cjs: {
+      target: ['node20'],
+    },
+  },
+})
+```
+
+This allows different targets, platforms, or other settings per format.
+
+## Common Patterns
+
+### Modern Library (ESM + CJS)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+})
+```
+
+Output:
+- `dist/index.mjs` (ESM)
+- `dist/index.cjs` (CJS)
+- `dist/index.d.ts` (Types)
+
+### Browser Library (IIFE)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['iife'],
+  globalName: 'MyLib',
+  platform: 'browser',
+  minify: true,
+})
+```
+
+Output: `dist/index.global.js` (IIFE with global `MyLib`)
+
+### Universal Library (UMD)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['umd'],
+  globalName: 'MyLib',
+  platform: 'neutral',
+})
+```
+
+Works with AMD, CommonJS, and browser globals.
+
+### Node.js Package (CJS + ESM)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  platform: 'node',
+  dts: true,
+  shims: true, // Add __dirname, __filename for CJS compat
+})
+```
+
+### Framework Component Library
+
+```ts
+export default defineConfig({
+  entry: ['src/index.tsx'],
+  format: ['esm', 'cjs'],
+  deps: {
+    neverBundle: ['react', 'react-dom'], // Don't bundle dependencies
+  },
+  dts: true,
+})
+```
+
+## Format-Specific Outputs
+
+### File Extensions
+
+| Format | Extension |
+|--------|-----------|
+| ESM | `.mjs` or `.js` (with `"type": "module"`) |
+| CJS | `.cjs` or `.js` (without `"type": "module"`) |
+| IIFE | `.global.js` |
+| UMD | `.umd.js` |
+
+### Customize Extensions
+
+Use `outExtensions` to override:
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  outExtensions: ({ format }) => ({
+    js: format === 'esm' ? '.js' : '.cjs',
+  }),
+})
+```
+
+## Tips
+
+1. **Use ESM + CJS** for maximum compatibility
+2. **Use IIFE** for browser-only libraries
+3. **Use UMD** for universal compatibility (less common now)
+4. **Externalize dependencies** to avoid bundling framework code
+5. **Add shims** for CJS compatibility when using Node.js APIs
+6. **Set globalName** for IIFE/UMD formats
+
+## Related Options
+
+- [Target](option-target.md) - Set JavaScript version
+- [Platform](option-platform.md) - Set platform (node, browser, neutral)
+- [Shims](option-shims.md) - Add ESM/CJS compatibility
+- [Output Directory](option-output-directory.md) - Customize output paths