devskill 2.0.2

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

@@ -0,0 +1,299 @@
+# Shims
+
+Add compatibility between ESM and CommonJS module systems.
+
+## Overview
+
+Shims provide small pieces of code that bridge the gap between CommonJS (CJS) and ECMAScript Modules (ESM), enabling cross-module-system compatibility.
+
+## What Shims Provide
+
+### ESM Output (when enabled)
+
+With `shims: true`, adds CommonJS variables to ESM:
+
+- `__dirname` - Current directory path
+- `__filename` - Current file path
+
+### ESM Output (automatic)
+
+Always added when using `require` in ESM on Node.js:
+
+- `require` function via `createRequire(import.meta.url)`
+
+### CJS Output (automatic)
+
+Always added to CommonJS output:
+
+- `import.meta.url`
+- `import.meta.dirname`
+- `import.meta.filename`
+
+## Usage
+
+### CLI
+
+```bash
+tsdown --shims
+```
+
+### Config File
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  shims: true,
+})
+```
+
+## Generated Code
+
+### ESM with Shims
+
+**Source:**
+```ts
+console.log(__dirname)
+console.log(__filename)
+```
+
+**Output (shims: true):**
+```js
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+console.log(__dirname)
+console.log(__filename)
+```
+
+### ESM with require
+
+**Source:**
+```ts
+const mod = require('some-module')
+```
+
+**Output (automatic on Node.js):**
+```js
+import { createRequire } from 'node:module'
+const require = createRequire(import.meta.url)
+
+const mod = require('some-module')
+```
+
+### CJS with import.meta
+
+**Source:**
+```ts
+console.log(import.meta.url)
+console.log(import.meta.dirname)
+```
+
+**Output (automatic):**
+```js
+const import_meta = {
+  url: require('url').pathToFileURL(__filename).toString(),
+  dirname: __dirname,
+  filename: __filename
+}
+
+console.log(import_meta.url)
+console.log(import_meta.dirname)
+```
+
+## Common Patterns
+
+### Node.js CLI Tool
+
+```ts
+export default defineConfig({
+  entry: ['src/cli.ts'],
+  format: ['esm'],
+  platform: 'node',
+  shims: true,  // Add __dirname, __filename
+})
+```
+
+### Dual Format Library
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  platform: 'node',
+  shims: true,  // ESM gets __dirname/__filename
+                // CJS gets import.meta.* (automatic)
+})
+```
+
+### Server-Side Code
+
+```ts
+export default defineConfig({
+  entry: ['src/server.ts'],
+  format: ['esm'],
+  platform: 'node',
+  shims: true,
+  deps: {
+    neverBundle: [/.*/],  // External all deps
+  },
+})
+```
+
+### File System Operations
+
+```ts
+// Source code
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Read file relative to current module
+const content = readFileSync(join(__dirname, 'data.json'), 'utf-8')
+```
+
+```ts
+// tsdown config
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  shims: true,  // Enables __dirname
+})
+```
+
+## When to Use Shims
+
+### Use `shims: true` when:
+
+- ✅ Building Node.js tools/CLIs
+- ✅ Code uses `__dirname` or `__filename`
+- ✅ Need file system operations relative to module
+- ✅ Migrating from CommonJS to ESM
+- ✅ Need cross-format compatibility
+
+### Don't need shims when:
+
+- ❌ Browser-only code
+- ❌ No file system operations
+- ❌ Using only `import.meta.url`
+- ❌ Pure ESM without CJS variables
+
+## Performance Impact
+
+### Runtime Overhead
+
+Shims add minimal runtime overhead:
+
+```js
+// Added to output when shims enabled
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+```
+
+### Tree Shaking
+
+If `__dirname` or `__filename` are not used, they're automatically removed during bundling (no overhead).
+
+## Platform Considerations
+
+### Node.js Platform
+
+```ts
+export default defineConfig({
+  platform: 'node',
+  format: ['esm'],
+  shims: true,  // Recommended for Node.js
+})
+```
+
+- `require` shim added automatically
+- `__dirname` and `__filename` available with `shims: true`
+
+### Browser Platform
+
+```ts
+export default defineConfig({
+  platform: 'browser',
+  format: ['esm'],
+  shims: false,  // Not needed for browser
+})
+```
+
+- Shims not needed (no Node.js variables)
+- Will cause warnings if Node.js APIs used
+
+### Neutral Platform
+
+```ts
+export default defineConfig({
+  platform: 'neutral',
+  format: ['esm'],
+  shims: false,  // Avoid platform-specific code
+})
+```
+
+- Avoid shims for maximum portability
+
+## CLI Examples
+
+```bash
+# Enable shims
+tsdown --shims
+
+# ESM with shims for Node.js
+tsdown --format esm --platform node --shims
+
+# Dual format with shims
+tsdown --format esm --format cjs --shims
+```
+
+## Troubleshooting
+
+### `__dirname is not defined`
+
+Enable shims:
+
+```ts
+export default defineConfig({
+  shims: true,
+})
+```
+
+### `require is not defined` in ESM
+
+Automatic on Node.js platform. If not working:
+
+```ts
+export default defineConfig({
+  platform: 'node',  // Ensure Node.js platform
+})
+```
+
+### Import.meta not working in CJS
+
+Automatic - no configuration needed. If still failing, check output format:
+
+```ts
+export default defineConfig({
+  format: ['cjs'],  // Shims added automatically
+})
+```
+
+## Tips
+
+1. **Enable for Node.js tools** - Use `shims: true` for CLIs and servers
+2. **Skip for browsers** - Not needed for browser code
+3. **No overhead if unused** - Automatically tree-shaken
+4. **Automatic require shim** - No config needed for `require` in ESM
+5. **CJS shims automatic** - `import.meta.*` always available in CJS
+
+## Related Options
+
+- [Platform](option-platform.md) - Runtime environment
+- [Output Format](option-output-format.md) - Module formats
+- [Target](option-target.md) - Syntax transformations

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

@@ -0,0 +1,301 @@
+# Source Maps
+
+Generate source maps for debugging bundled code.
+
+## Overview
+
+Source maps map minified/bundled code back to original source files, making debugging significantly easier by showing original line numbers and variable names.
+
+## Basic Usage
+
+### CLI
+
+```bash
+tsdown --sourcemap
+
+# Or inline
+tsdown --sourcemap inline
+```
+
+### Config File
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  sourcemap: true,
+})
+```
+
+## Source Map Types
+
+### External (default)
+
+Generates separate `.map` files:
+
+```ts
+export default defineConfig({
+  sourcemap: true,  // or 'external'
+})
+```
+
+**Output:**
+- `dist/index.mjs`
+- `dist/index.mjs.map`
+
+**Pros:**
+- Smaller bundle size
+- Can be excluded from production
+- Faster parsing
+
+### Inline
+
+Embeds source maps in the bundle:
+
+```ts
+export default defineConfig({
+  sourcemap: 'inline',
+})
+```
+
+**Output:**
+- `dist/index.mjs` (includes source map as data URL)
+
+**Pros:**
+- Single file deployment
+- Guaranteed to be available
+
+**Cons:**
+- Larger bundle size
+- Exposed in production
+
+### Hidden
+
+Generates map files without reference comment:
+
+```ts
+export default defineConfig({
+  sourcemap: 'hidden',
+})
+```
+
+**Output:**
+- `dist/index.mjs` (no `//# sourceMappingURL` comment)
+- `dist/index.mjs.map`
+
+**Use when:**
+- You want maps for error reporting tools
+- But don't want them exposed to users
+
+## Auto-Enable Scenarios
+
+### Declaration Maps
+
+If `declarationMap` is enabled in `tsconfig.json`, source maps are automatically enabled:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "declarationMap": true
+  }
+}
+```
+
+This also generates `.d.ts.map` files for TypeScript declarations.
+
+## Common Patterns
+
+### Development Build
+
+```ts
+export default defineConfig((options) => ({
+  entry: ['src/index.ts'],
+  sourcemap: options.watch,  // Only in dev
+  minify: !options.watch,
+}))
+```
+
+### Production with External Maps
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  sourcemap: true,  // External maps
+  minify: true,
+})
+```
+
+Deploy maps to separate error reporting service.
+
+### Always Inline (Development Tool)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  sourcemap: 'inline',
+})
+```
+
+### Per-Format Source Maps
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: {
+    esm: {
+      sourcemap: true,
+    },
+    iife: {
+      sourcemap: 'inline',  // Inline for browser
+    },
+  },
+})
+```
+
+### TypeScript Library with Declaration Maps
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  sourcemap: true,
+  dts: {
+    sourcemap: true,  // Enable declaration maps
+  },
+})
+```
+
+**Output:**
+- `dist/index.mjs` + `dist/index.mjs.map`
+- `dist/index.cjs` + `dist/index.cjs.map`
+- `dist/index.d.ts` + `dist/index.d.ts.map`
+
+## Benefits
+
+### For Development
+
+- **Faster debugging** - See original code in debugger
+- **Better error messages** - Stack traces show original lines
+- **Easier breakpoints** - Set breakpoints on source code
+
+### For Production
+
+- **Error reporting** - Send accurate error locations to services
+- **Monitoring** - Track errors back to source
+- **Support** - Help users report issues accurately
+
+## Performance Impact
+
+| Type | Bundle Size | Parse Speed | Debugging |
+|------|-------------|-------------|-----------|
+| None | Smallest | Fastest | Hard |
+| External | Small | Fast | Easy |
+| Inline | Largest | Slower | Easy |
+| Hidden | Small | Fast | Tools only |
+
+## CLI Examples
+
+```bash
+# Enable source maps
+tsdown --sourcemap
+
+# Inline source maps
+tsdown --sourcemap inline
+
+# Hidden source maps
+tsdown --sourcemap hidden
+
+# Development with source maps
+tsdown --watch --sourcemap
+
+# Production with external maps
+tsdown --minify --sourcemap
+
+# No source maps
+tsdown --no-sourcemap
+```
+
+## Use Cases
+
+### Local Development
+
+```ts
+export default defineConfig({
+  sourcemap: true,
+  minify: false,
+})
+```
+
+### Production Build
+
+```ts
+export default defineConfig({
+  sourcemap: 'external',  // Upload to error service
+  minify: true,
+})
+```
+
+### Browser Library
+
+```ts
+export default defineConfig({
+  format: ['iife'],
+  platform: 'browser',
+  sourcemap: 'inline',  // Self-contained
+  globalName: 'MyLib',
+})
+```
+
+### Node.js CLI Tool
+
+```ts
+export default defineConfig({
+  format: ['esm'],
+  platform: 'node',
+  sourcemap: true,
+  shims: true,
+})
+```
+
+## Troubleshooting
+
+### Source Maps Not Working
+
+1. **Check output** - Verify `.map` files are generated
+2. **Check reference** - Look for `//# sourceMappingURL=` comment
+3. **Check paths** - Ensure relative paths are correct
+4. **Check tool** - Verify debugger/browser supports source maps
+
+### Large Bundle Size
+
+Use external source maps instead of inline:
+
+```ts
+export default defineConfig({
+  sourcemap: true,  // Not 'inline'
+})
+```
+
+### Source Not Found
+
+- Ensure source files are accessible relative to map
+- Check `sourceRoot` in generated map
+- Verify paths in `sources` array
+
+## Tips
+
+1. **Use external maps** for production (smaller bundles)
+2. **Use inline maps** for single-file tools
+3. **Enable in development** for better DX
+4. **Upload to error services** for production debugging
+5. **Use hidden maps** when you want them for tools only
+6. **Enable declaration maps** for TypeScript libraries
+
+## Related Options
+
+- [Minification](option-minification.md) - Code compression
+- [DTS](option-dts.md) - TypeScript declarations
+- [Watch Mode](option-watch-mode.md) - Development workflow
+- [Target](option-target.md) - Syntax transformations