devskill 2.0.2

package/skills/tsdown/references/option-config-file.md

@@ -0,0 +1,281 @@
+# Configuration File
+
+Centralize and manage build settings with a configuration file.
+
+## Overview
+
+tsdown searches for config files automatically in the current directory and parent directories.
+
+## Supported File Names
+
+tsdown looks for these files (in order):
+- `tsdown.config.ts`
+- `tsdown.config.mts`
+- `tsdown.config.cts`
+- `tsdown.config.js`
+- `tsdown.config.mjs`
+- `tsdown.config.cjs`
+- `tsdown.config.json`
+- `tsdown.config`
+- `package.json` (in `tsdown` field)
+
+## Basic Configuration
+
+### TypeScript Config
+
+```ts
+// tsdown.config.ts
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+})
+```
+
+### JavaScript Config
+
+```js
+// tsdown.config.js
+export default {
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+}
+```
+
+### JSON Config
+
+```json
+// tsdown.config.json
+{
+  "entry": ["src/index.ts"],
+  "format": ["esm", "cjs"],
+  "dts": true
+}
+```
+
+### Package.json Config
+
+```json
+// package.json
+{
+  "name": "my-library",
+  "tsdown": {
+    "entry": ["src/index.ts"],
+    "format": ["esm", "cjs"],
+    "dts": true
+  }
+}
+```
+
+## Multiple Configurations
+
+Build multiple outputs with different settings:
+
+```ts
+export default defineConfig([
+  {
+    entry: 'src/index.ts',
+    format: ['esm', 'cjs'],
+    platform: 'node',
+    dts: true,
+  },
+  {
+    entry: 'src/browser.ts',
+    format: ['iife'],
+    platform: 'browser',
+    globalName: 'MyLib',
+    minify: true,
+  },
+])
+```
+
+Each configuration runs as a separate build.
+
+## Dynamic Configuration
+
+Use a function for conditional config:
+
+```ts
+export default defineConfig((options) => {
+  const isDev = options.watch
+
+  return {
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs'],
+    minify: !isDev,
+    sourcemap: isDev,
+    clean: !isDev,
+  }
+})
+```
+
+Available options:
+- `watch` - Whether watch mode is enabled
+- Other CLI flags passed to config
+
+## Config Loaders
+
+Control how TypeScript config files are loaded:
+
+### Auto Loader (Default)
+
+Uses native TypeScript support if available, otherwise falls back to `unrun`:
+
+```bash
+tsdown # Uses auto loader
+```
+
+### Native Loader
+
+Uses runtime's native TypeScript support (Node.js 23+, Bun, Deno):
+
+```bash
+tsdown --config-loader native
+```
+
+### Unrun Loader
+
+Uses [unrun](https://gugustinette.github.io/unrun/) library for loading:
+
+```bash
+tsdown --config-loader unrun
+```
+
+**Tip:** Use `unrun` loader if you need to load TypeScript configs without file extensions in Node.js.
+
+## Custom Config Path
+
+Specify a custom config file location:
+
+```bash
+tsdown --config ./configs/build.config.ts
+# or
+tsdown -c custom-config.ts
+```
+
+## Disable Config File
+
+Ignore config files and use CLI options only:
+
+```bash
+tsdown --no-config src/index.ts --format esm
+```
+
+## Extend Vite/Vitest Config (Experimental)
+
+Reuse existing Vite or Vitest configurations:
+
+```bash
+# Extend vite.config.*
+tsdown --from-vite
+
+# Extend vitest.config.*
+tsdown --from-vite vitest
+```
+
+**Note:** Only specific options like `resolve` and `plugins` are reused. Test thoroughly as this feature is experimental.
+
+## Workspace / Monorepo
+
+Build multiple packages with a single config:
+
+```ts
+export default defineConfig({
+  workspace: 'packages/*',
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+})
+```
+
+Each package directory matching the glob pattern will be built with the same configuration.
+
+## Common Patterns
+
+### Library with Multiple Builds
+
+```ts
+export default defineConfig([
+  // Node.js build
+  {
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs'],
+    platform: 'node',
+    dts: true,
+  },
+  // Browser build
+  {
+    entry: ['src/browser.ts'],
+    format: ['iife'],
+    platform: 'browser',
+    globalName: 'MyLib',
+  },
+])
+```
+
+### Development vs Production
+
+```ts
+export default defineConfig((options) => ({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  minify: !options.watch,
+  sourcemap: options.watch ? true : false,
+  clean: !options.watch,
+}))
+```
+
+### Monorepo Root Config
+
+```ts
+// Root tsdown.config.ts
+export default defineConfig({
+  workspace: 'packages/*',
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+  // Shared config for all packages
+})
+```
+
+### Per-Package Override
+
+```ts
+// packages/special/tsdown.config.ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'], // Override: only ESM
+  platform: 'browser', // Override: browser only
+})
+```
+
+## Config Precedence
+
+When multiple configs exist:
+
+1. CLI options (highest priority)
+2. Config file specified with `--config`
+3. Auto-discovered config files
+4. Package.json `tsdown` field
+5. Default values
+
+## Tips
+
+1. **Use TypeScript config** for type checking and autocomplete
+2. **Use defineConfig** helper for better DX
+3. **Export arrays** for multiple build configurations
+4. **Use functions** for dynamic/conditional configs
+5. **Keep configs simple** - prefer convention over configuration
+6. **Use workspace** for monorepo builds
+7. **Test experimental features** thoroughly before production use
+
+## Related Options
+
+- [Entry](option-entry.md) - Configure entry points
+- [Output Format](option-output-format.md) - Output formats
+- [Watch Mode](option-watch-mode.md) - Watch mode configuration

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

@@ -0,0 +1,301 @@
+# CSS Support
+
+**Status: Experimental — API and behavior may change.**
+
+Configure CSS handling including preprocessors, syntax lowering, minification, and code splitting.
+
+## Getting Started
+
+All CSS support in `tsdown` is provided by the `@tsdown/css` package. Install it to enable CSS handling:
+
+```bash
+npm install -D @tsdown/css
+```
+
+When `@tsdown/css` is installed, CSS processing is automatically enabled. Without it, encountering CSS files will result in an error.
+
+## CSS Import
+
+Import `.css` files from TypeScript/JavaScript — CSS is extracted into separate `.css` assets:
+
+```ts
+// src/index.ts
+import './style.css'
+export function greet() { return 'Hello' }
+```
+
+Output: `index.mjs` + `index.css`
+
+### `@import` Inlining
+
+CSS `@import` statements are resolved and inlined automatically. No separate output files produced.
+
+### Inline CSS (`?inline`)
+
+Append `?inline` to return processed CSS as a JS string instead of emitting a `.css` file:
+
+```ts
+import './style.css'                   // → .css file
+import css from './theme.css?inline'   // → JS string
+```
+
+Works with preprocessors too (`./foo.scss?inline`). Goes through full pipeline (preprocessors, @import inlining, lowering, minification). Tree-shakeable (`moduleSideEffects: false`).
+
+## CSS Pre-processors
+
+Built-in support for Sass, Less, and Stylus. Install the preprocessor:
+
+```bash
+# Sass (either one)
+npm install -D sass-embedded  # recommended, faster
+npm install -D sass
+
+# Less
+npm install -D less
+
+# Stylus
+npm install -D stylus
+```
+
+Then import directly:
+
+```ts
+import './style.scss'
+import './theme.less'
+import './global.styl'
+```
+
+### Preprocessor Options
+
+```ts
+export default defineConfig({
+  css: {
+    preprocessorOptions: {
+      scss: {
+        additionalData: `$brand-color: #ff7e17;`,
+      },
+      less: {
+        math: 'always',
+      },
+      stylus: {
+        define: { '$brand-color': '#ff7e17' },
+      },
+    },
+  },
+})
+```
+
+### `additionalData`
+
+Inject code at the beginning of every preprocessor file:
+
+```ts
+// String form
+scss: {
+  additionalData: `@use "src/styles/variables" as *;`,
+}
+
+// Function form
+scss: {
+  additionalData: (source, filename) => {
+    if (filename.includes('theme')) return source
+    return `@use "src/styles/variables" as *;\n${source}`
+  },
+}
+```
+
+## CSS Minification
+
+```ts
+export default defineConfig({
+  css: {
+    minify: true,
+  },
+})
+```
+
+Powered by Lightning CSS.
+
+## CSS Target
+
+Override the top-level `target` specifically for CSS:
+
+```ts
+export default defineConfig({
+  target: 'node18',
+  css: {
+    target: 'chrome90', // CSS-specific target
+  },
+})
+```
+
+Set `css.target: false` to disable CSS syntax lowering entirely.
+
+## CSS Transformer
+
+`css.transformer` controls mutually exclusive CSS processing paths:
+
+- `'lightningcss'` (default): `@import` via Lightning CSS `bundleAsync()`, no PostCSS.
+- `'postcss'`: `@import` via `postcss-import`, PostCSS plugins applied, Lightning CSS for final transform only.
+
+```ts
+export default defineConfig({
+  css: {
+    transformer: 'postcss',
+  },
+})
+```
+
+### PostCSS Options
+
+```ts
+export default defineConfig({
+  css: {
+    transformer: 'postcss',
+    postcss: {
+      plugins: [require('autoprefixer')],
+    },
+    // Or: postcss: './config' — path to search for postcss.config.js
+  },
+})
+```
+
+Auto-detects PostCSS config from project root when `transformer` is `'postcss'` and `css.postcss` is omitted.
+
+## Lightning CSS (Syntax Lowering)
+
+Install `lightningcss` to enable CSS syntax lowering based on your `target`:
+
+```bash
+npm install -D lightningcss
+```
+
+When `target` is set (e.g., `target: 'chrome108'`), modern CSS features are automatically downleveled:
+
+```css
+/* Input */
+.foo { & .bar { color: red } }
+
+/* Output (chrome108) */
+.foo .bar { color: red }
+```
+
+### Custom Lightning CSS Options
+
+```ts
+import { Features } from 'lightningcss'
+
+export default defineConfig({
+  css: {
+    lightningcss: {
+      targets: { chrome: 100 << 16 },
+      include: Features.Nesting,
+    },
+  },
+})
+```
+
+`css.lightningcss.targets` takes precedence over both `target` and `css.target` for CSS.
+
+## CSS Modules
+
+Files with `.module.css` (and `.module.scss`, `.module.less`, etc.) are treated as CSS modules — class names are scoped and exported as JS:
+
+```ts
+import styles from './app.module.css'
+console.log(styles.title) // "scoped_title_hash"
+```
+
+### Configuration
+
+```ts
+export default defineConfig({
+  css: {
+    modules: {
+      scopeBehaviour: 'local',             // 'local' (default) | 'global'
+      generateScopedName: '[hash]_[local]', // Lightning CSS pattern string
+      localsConvention: 'camelCase',       // 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly'
+    },
+  },
+})
+```
+
+Set `css.modules: false` to disable. Function-form `generateScopedName` requires `transformer: 'postcss'`.
+
+### Optional Dependencies (PostCSS path)
+
+```bash
+npm install -D postcss postcss-modules
+```
+
+## Code Splitting
+
+### Merged (Default)
+
+All CSS merged into a single file (default: `style.css`).
+
+```ts
+export default defineConfig({
+  css: {
+    fileName: 'my-library.css', // Custom name (default: 'style.css')
+  },
+})
+```
+
+### Per-Chunk Splitting
+
+```ts
+export default defineConfig({
+  css: {
+    splitting: true, // Each JS chunk gets a corresponding .css file
+  },
+})
+```
+
+## Preserving CSS Imports (`css.inject`)
+
+When enabled, JS output preserves `import` statements pointing to emitted CSS files. Consumers auto-import CSS alongside JS:
+
+```ts
+export default defineConfig({
+  css: {
+    inject: true,
+  },
+})
+```
+
+## PostCSS Optional Peer Dependencies
+
+When using `transformer: 'postcss'`, install these as needed:
+
+| Package | Purpose | Required When |
+|---------|---------|---------------|
+| `postcss` | Core PostCSS engine | Always (with `transformer: 'postcss'`) |
+| `postcss-import` | Resolve/inline `@import` | CSS uses `@import` |
+| `postcss-modules` | CSS modules (scoped classes) | Using `.module.css` files |
+
+```bash
+npm install -D postcss postcss-import postcss-modules
+```
+
+All declared as optional peer dependencies of `@tsdown/css`.
+
+## Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `css.transformer` | `'postcss' \| 'lightningcss'` | `'lightningcss'` | CSS processing pipeline |
+| `css.splitting` | `boolean` | `false` | Per-chunk CSS splitting |
+| `css.fileName` | `string` | `'style.css'` | Merged CSS file name |
+| `css.minify` | `boolean` | `false` | CSS minification |
+| `css.modules` | `object \| false` | `{}` | CSS modules config, or `false` to disable |
+| `css.inject` | `boolean` | `false` | Preserve CSS imports in JS output |
+| `css.target` | `string \| string[] \| false` | _from `target`_ | CSS-specific lowering target |
+| `css.postcss` | `string \| object` | — | PostCSS config path or inline options |
+| `css.preprocessorOptions` | `object` | — | Preprocessor options |
+| `css.lightningcss` | `object` | — | Lightning CSS options |
+
+## Related
+
+- [Target](option-target.md) - Configure syntax lowering targets
+- [Output Format](option-output-format.md) - Module output formats