devskill 2.0.2

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

@@ -0,0 +1,385 @@
+# Dependencies
+
+Control how dependencies are bundled or externalized.
+
+## Overview
+
+tsdown intelligently handles dependencies to keep your library lightweight while ensuring all necessary code is included.
+
+## Default Behavior
+
+### Auto-Externalized
+
+These are **NOT bundled** by default:
+
+- **`dependencies`** - Installed automatically with your package
+- **`peerDependencies`** - User must install manually
+- **`optionalDependencies`** - May or may not be installed depending on platform/config
+
+### Conditionally Bundled
+
+These are **bundled ONLY if imported**:
+
+- **`devDependencies`** - Only if actually used in source code
+- **Phantom dependencies** - In node_modules but not in package.json
+
+## Configuration Options
+
+All dependency options are grouped under the `deps` field:
+
+```ts
+export default defineConfig({
+  deps: {
+    neverBundle: ['react', /^@myorg\//],
+    alwaysBundle: ['some-package'],
+    onlyBundle: ['cac', 'bumpp'],
+    skipNodeModulesBundle: true,
+  },
+})
+```
+
+### `deps.neverBundle`
+
+Mark dependencies as external (not bundled):
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  deps: {
+    neverBundle: [
+      'react',              // Single package
+      'react-dom',
+      /^@myorg\//,         // Regex pattern (all @myorg/* packages)
+      /^lodash/,           // All lodash packages
+    ],
+  },
+})
+```
+
+### `deps.alwaysBundle`
+
+Force dependencies to be bundled:
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  deps: {
+    alwaysBundle: [
+      'some-package',      // Bundle this even if in dependencies
+      'vendor-lib',
+    ],
+  },
+})
+```
+
+### `deps.onlyBundle`
+
+Whitelist of dependencies allowed to be bundled from node_modules. Throws an error if any unlisted dependency is bundled:
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  deps: {
+    onlyBundle: [
+      'cac',               // Allow bundling cac
+      'bumpp',             // Allow bundling bumpp
+      /^my-utils/,         // Regex patterns supported
+    ],
+  },
+})
+```
+
+**Behavior:**
+- **Array** (`['cac', /^my-/]`): Only matching dependencies can be bundled. Error for others.
+- **`false`**: Suppress all warnings about bundled dependencies.
+- **Not set** (default): Warns if any node_modules dependencies are bundled.
+
+**Note:** Include all sub-dependencies in the list, not just top-level imports.
+
+### `deps.skipNodeModulesBundle`
+
+Skip resolving and bundling ALL node_modules:
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  deps: {
+    skipNodeModulesBundle: true,
+  },
+})
+```
+
+**Result:** No dependencies from node_modules are parsed or bundled.
+
+**Note:** Cannot be used together with `alwaysBundle`.
+
+## Common Patterns
+
+### React Component Library
+
+```ts
+export default defineConfig({
+  entry: ['src/index.tsx'],
+  format: ['esm', 'cjs'],
+  deps: {
+    neverBundle: [
+      'react',
+      'react-dom',
+      /^react\//,          // react/jsx-runtime, etc.
+    ],
+  },
+  dts: true,
+})
+```
+
+### Utility Library with Shared Deps
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  deps: {
+    alwaysBundle: ['lodash-es'],
+  },
+  dts: true,
+})
+```
+
+### Monorepo Package
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  deps: {
+    neverBundle: [
+      /^@mycompany\//,     // Don't bundle other workspace packages
+    ],
+  },
+  dts: true,
+})
+```
+
+### CLI Tool (Bundle Everything)
+
+```ts
+export default defineConfig({
+  entry: ['src/cli.ts'],
+  format: ['esm'],
+  platform: 'node',
+  deps: {
+    alwaysBundle: [/.*/],
+  },
+  shims: true,
+})
+```
+
+### Library with Specific Externals
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  deps: {
+    neverBundle: [
+      'vue',
+      '@vue/runtime-core',
+      '@vue/reactivity',
+    ],
+  },
+  dts: true,
+})
+```
+
+## Declaration Files
+
+Dependency handling for `.d.ts` files follows the same rules as JavaScript.
+
+### Complex Type Resolution
+
+Use TypeScript resolver for complex third-party types:
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  dts: {
+    resolver: 'tsc',     // Use TypeScript resolver instead of Oxc
+  },
+})
+```
+
+**When to use `tsc` resolver:**
+- Types in `@types/*` packages with non-standard naming (e.g., `@types/babel__generator`)
+- Complex type dependencies
+- Issues with default Oxc resolver
+
+**Trade-off:** `tsc` is slower but more compatible.
+
+## CLI Usage
+
+### Never Bundle
+
+```bash
+tsdown --deps.never-bundle react --deps.never-bundle react-dom
+tsdown --deps.never-bundle '/^@myorg\/.*/'
+```
+
+### Skip Node Modules
+
+```bash
+tsdown --deps.skip-node-modules-bundle
+```
+
+## Migration from Deprecated Options
+
+| Deprecated Option | New Option |
+|---|---|
+| `external` | `deps.neverBundle` |
+| `noExternal` | `deps.alwaysBundle` |
+| `inlineOnly` | `deps.onlyBundle` |
+| `deps.onlyAllowBundle` | `deps.onlyBundle` |
+| `skipNodeModulesBundle` | `deps.skipNodeModulesBundle` |
+
+## Examples by Use Case
+
+### Framework Component
+
+```ts
+// Don't bundle framework
+export default defineConfig({
+  deps: {
+    neverBundle: ['vue', 'react', 'solid-js', 'svelte'],
+  },
+})
+```
+
+### Standalone App
+
+```ts
+// Bundle everything
+export default defineConfig({
+  deps: {
+    alwaysBundle: [/.*/],
+  },
+})
+```
+
+### Shared Library
+
+```ts
+// Bundle only specific utils
+export default defineConfig({
+  deps: {
+    neverBundle: [/.*/],        // External by default
+    alwaysBundle: ['tiny-utils'], // Except this one
+  },
+})
+```
+
+### Monorepo Package
+
+```ts
+// External workspace packages, bundle utilities
+export default defineConfig({
+  deps: {
+    neverBundle: [
+      /^@workspace\//,     // Other workspace packages
+      'react',
+      'react-dom',
+    ],
+    alwaysBundle: [
+      'lodash-es',         // Bundle utility libraries
+    ],
+  },
+})
+```
+
+## Troubleshooting
+
+### Dependency Bundled Unexpectedly
+
+Check if it's in `devDependencies` and imported. Move to `dependencies`:
+
+```json
+{
+  "dependencies": {
+    "should-be-external": "^1.0.0"
+  }
+}
+```
+
+Or explicitly externalize:
+
+```ts
+export default defineConfig({
+  deps: {
+    neverBundle: ['should-be-external'],
+  },
+})
+```
+
+### Missing Dependency at Runtime
+
+Ensure it's in `dependencies`, `peerDependencies`, or `optionalDependencies`:
+
+```json
+{
+  "dependencies": {
+    "needed-package": "^1.0.0"
+  }
+}
+```
+
+Or bundle it:
+
+```ts
+export default defineConfig({
+  deps: {
+    alwaysBundle: ['needed-package'],
+  },
+})
+```
+
+### Type Resolution Errors
+
+Use TypeScript resolver for complex types:
+
+```ts
+export default defineConfig({
+  dts: {
+    resolver: 'tsc',
+  },
+})
+```
+
+## Summary
+
+**Default behavior:**
+- `dependencies`, `peerDependencies`, & `optionalDependencies` → External
+- `devDependencies` & phantom deps → Bundled if imported
+
+**Override (under `deps`):**
+- `neverBundle` → Force external
+- `alwaysBundle` → Force bundled
+- `onlyBundle` → Whitelist bundled deps
+- `skipNodeModulesBundle` → Skip all node_modules
+
+**Declaration files:**
+- Same bundling logic as JavaScript
+- Use `resolver: 'tsc'` for complex types
+
+## Tips
+
+1. **Keep dependencies external** for libraries
+2. **Bundle everything** for standalone CLIs
+3. **Use regex patterns** for namespaced packages
+4. **Check bundle size** to verify external/bundled split
+5. **Test with fresh install** to catch missing dependencies
+6. **Use tsc resolver** only when needed (slower)
+
+## Related Options
+
+- [External](option-dependencies.md) - This page
+- [Platform](option-platform.md) - Runtime environment
+- [Output Format](option-output-format.md) - Module formats
+- [DTS](option-dts.md) - Type declarations

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

@@ -0,0 +1,251 @@
+# TypeScript Declaration Files
+
+Generate `.d.ts` type declaration files for your library.
+
+## Overview
+
+tsdown uses [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts) to generate and bundle TypeScript declaration files.
+
+**Requirements:**
+- TypeScript must be installed in your project
+
+## Enabling DTS Generation
+
+### Auto-Enabled
+
+DTS generation is **automatically enabled** if `package.json` contains:
+- `types` field, or
+- `typings` field
+
+### Manual Enable
+
+#### CLI
+
+```bash
+tsdown --dts
+```
+
+#### Config File
+
+```ts
+export default defineConfig({
+  dts: true,
+})
+```
+
+## Performance
+
+### With `isolatedDeclarations` (Recommended)
+
+**Extremely fast** - uses oxc-transform for generation.
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "isolatedDeclarations": true
+  }
+}
+```
+
+### Without `isolatedDeclarations`
+
+Falls back to TypeScript compiler. Reliable but slower.
+
+## Declaration Maps
+
+Map `.d.ts` files back to original `.ts` sources (useful for monorepos).
+
+### Enable in tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "declarationMap": true
+  }
+}
+```
+
+### Enable in tsdown Config
+
+```ts
+export default defineConfig({
+  dts: {
+    sourcemap: true,
+  },
+})
+```
+
+## Advanced Options
+
+### Custom Compiler Options
+
+Override TypeScript compiler options:
+
+```ts
+export default defineConfig({
+  dts: {
+    compilerOptions: {
+      removeComments: false,
+    },
+  },
+})
+```
+
+## Build Process
+
+- **ESM format**: `.js` and `.d.ts` files generated in same build
+- **CJS format**: Separate build process for `.d.ts` files
+
+## Common Patterns
+
+### Basic Library
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+})
+```
+
+Output:
+- `dist/index.mjs`
+- `dist/index.cjs`
+- `dist/index.d.ts`
+
+### Multiple Entry Points
+
+```ts
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    utils: 'src/utils.ts',
+  },
+  format: ['esm', 'cjs'],
+  dts: true,
+})
+```
+
+Output:
+- `dist/index.mjs`, `dist/index.cjs`, `dist/index.d.ts`
+- `dist/utils.mjs`, `dist/utils.cjs`, `dist/utils.d.ts`
+
+### With Monorepo Support
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: {
+    sourcemap: true, // Enable declaration maps
+  },
+})
+```
+
+### Fast Build (Isolated Declarations)
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "isolatedDeclarations": true,
+    "declaration": true,
+    "declarationMap": true
+  }
+}
+```
+
+```ts
+// tsdown.config.ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true, // Will use fast oxc-transform
+})
+```
+
+## Troubleshooting
+
+### Missing Types
+
+Ensure TypeScript is installed:
+
+```bash
+pnpm add -D typescript
+```
+
+### Slow Generation
+
+Enable `isolatedDeclarations` in `tsconfig.json` for faster builds.
+
+### Declaration Errors
+
+Check that all exports have explicit types (required for `isolatedDeclarations`).
+
+### Report Issues
+
+For DTS-specific issues, report to [rolldown-plugin-dts](https://github.com/sxzz/rolldown-plugin-dts/issues).
+
+### Vue Support
+
+Enable Vue component type generation (requires `vue-tsc`):
+
+```ts
+export default defineConfig({
+  dts: {
+    vue: true,
+  },
+})
+```
+
+### Oxc Transform
+
+Control Oxc usage for declaration generation:
+
+```ts
+export default defineConfig({
+  dts: {
+    oxc: true,  // Use oxc-transform (fast, requires isolatedDeclarations)
+  },
+})
+```
+
+### Custom TSConfig
+
+Specify a different tsconfig for DTS generation:
+
+```ts
+export default defineConfig({
+  dts: {
+    tsconfig: './tsconfig.build.json',
+  },
+})
+```
+
+## Available DTS Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `sourcemap` | `boolean` | Generate declaration source maps |
+| `compilerOptions` | `object` | Override TypeScript compiler options |
+| `vue` | `boolean` | Enable Vue type generation (requires vue-tsc) |
+| `oxc` | `boolean` | Use oxc-transform for fast generation |
+| `tsconfig` | `string` | Path to tsconfig file |
+| `resolver` | `'oxc' \| 'tsc'` | Module resolver: `'oxc'` (default, fast) or `'tsc'` (more compatible) |
+| `cjsDefault` | `boolean` | CJS default export handling |
+| `sideEffects` | `boolean` | Preserve side effects in declarations |
+
+## Tips
+
+1. **Always enable DTS** for TypeScript libraries
+2. **Use isolatedDeclarations** for fast builds
+3. **Enable declaration maps** in monorepos
+4. **Ensure explicit types** for all exports
+5. **Install TypeScript** as dev dependency
+
+## Related Options
+
+- [Entry](option-entry.md) - Configure entry points
+- [Output Format](option-output-format.md) - Multiple output formats
+- [Target](option-target.md) - JavaScript version