ads-fe 0.0.1

package/skills/tsdown/references/advanced-programmatic.md

@@ -0,0 +1,378 @@
+# Programmatic Usage
+
+Use tsdown from JavaScript/TypeScript code.
+
+## Overview
+
+tsdown can be imported and used programmatically in your Node.js scripts, custom build tools, or automation workflows.
+
+## Basic Usage
+
+### Simple Build
+
+```ts
+import { build } from 'tsdown'
+
+await build({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+})
+```
+
+### With Options
+
+```ts
+import { build } from 'tsdown'
+
+await build({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  outDir: 'dist',
+  dts: true,
+  minify: true,
+  sourcemap: true,
+  clean: true,
+})
+```
+
+## API Reference
+
+### build()
+
+Main function to run a build.
+
+```ts
+import { build } from 'tsdown'
+
+await build(options)
+```
+
+**Parameters:**
+- `options` - Build configuration object (same as config file)
+
+**Returns:**
+- `Promise<void>` - Resolves when build completes
+
+**Throws:**
+- Build errors if compilation fails
+
+## Configuration Object
+
+All config file options are available:
+
+```ts
+import { build, defineConfig } from 'tsdown'
+
+const config = defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  minify: true,
+  sourcemap: true,
+  deps: {
+    neverBundle: ['react', 'react-dom'],
+  },
+  plugins: [/* plugins */],
+  hooks: {
+    'build:done': async () => {
+      console.log('Build complete!')
+    },
+  },
+})
+
+await build(config)
+```
+
+See [Config Reference](option-config-file.md) for all options.
+
+## Common Patterns
+
+### Custom Build Script
+
+```ts
+// scripts/build.ts
+import { build } from 'tsdown'
+
+async function main() {
+  console.log('Building library...')
+
+  await build({
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs'],
+    dts: true,
+    clean: true,
+  })
+
+  console.log('Build complete!')
+}
+
+main().catch(console.error)
+```
+
+Run with:
+```bash
+tsx scripts/build.ts
+```
+
+### Multiple Builds
+
+```ts
+import { build } from 'tsdown'
+
+// Build main library
+await build({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  outDir: 'dist',
+  dts: true,
+})
+
+// Build CLI tool
+await build({
+  entry: ['src/cli.ts'],
+  format: ['esm'],
+  outDir: 'dist/bin',
+  platform: 'node',
+  shims: true,
+})
+```
+
+### Conditional Build
+
+```ts
+import { build } from 'tsdown'
+
+const isDev = process.env.NODE_ENV === 'development'
+
+await build({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  minify: !isDev,
+  sourcemap: isDev,
+  clean: !isDev,
+})
+```
+
+### With Error Handling
+
+```ts
+import { build } from 'tsdown'
+
+try {
+  await build({
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs'],
+    dts: true,
+  })
+  console.log('✅ Build successful')
+} catch (error) {
+  console.error('❌ Build failed:', error)
+  process.exit(1)
+}
+```
+
+### Automated Workflow
+
+```ts
+import { build } from 'tsdown'
+import { execSync } from 'child_process'
+
+async function release() {
+  // Clean
+  console.log('Cleaning...')
+  execSync('rm -rf dist')
+
+  // Build
+  console.log('Building...')
+  await build({
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs'],
+    dts: true,
+    minify: true,
+  })
+
+  // Test
+  console.log('Testing...')
+  execSync('npm test')
+
+  // Publish
+  console.log('Publishing...')
+  execSync('npm publish')
+}
+
+release().catch(console.error)
+```
+
+### Build with Post-Processing
+
+```ts
+import { build } from 'tsdown'
+import { copyFileSync } from 'fs'
+
+await build({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  hooks: {
+    'build:done': async () => {
+      // Copy additional files
+      copyFileSync('README.md', 'dist/README.md')
+      copyFileSync('LICENSE', 'dist/LICENSE')
+      console.log('Copied additional files')
+    },
+  },
+})
+```
+
+## Watch Mode
+
+Unfortunately, watch mode is not directly exposed in the programmatic API. Use the CLI for watch mode:
+
+```ts
+// Use CLI for watch mode
+import { spawn } from 'child_process'
+
+spawn('tsdown', ['--watch'], {
+  stdio: 'inherit',
+  shell: true,
+})
+```
+
+## Integration Examples
+
+### With Task Runner
+
+```ts
+// gulpfile.js
+import { build } from 'tsdown'
+import gulp from 'gulp'
+
+gulp.task('build', async () => {
+  await build({
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs'],
+    dts: true,
+  })
+})
+
+gulp.task('watch', () => {
+  return gulp.watch('src/**/*.ts', gulp.series('build'))
+})
+```
+
+### With Custom CLI
+
+```ts
+// scripts/cli.ts
+import { build } from 'tsdown'
+import { Command } from 'commander'
+
+const program = new Command()
+
+program
+  .command('build')
+  .option('--prod', 'Production build')
+  .action(async (options) => {
+    await build({
+      entry: ['src/index.ts'],
+      format: ['esm', 'cjs'],
+      minify: options.prod,
+      sourcemap: !options.prod,
+    })
+  })
+
+program.parse()
+```
+
+### With CI/CD
+
+```ts
+// .github/scripts/build.ts
+import { build } from 'tsdown'
+
+const isCI = process.env.CI === 'true'
+
+await build({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  minify: isCI,
+  clean: true,
+})
+
+// Upload to artifact storage
+if (isCI) {
+  // Upload dist/ to S3, etc.
+}
+```
+
+## TypeScript Support
+
+```ts
+// scripts/build.ts
+import { build, type UserConfig } from 'tsdown'
+
+const config: UserConfig = {
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+}
+
+await build(config)
+```
+
+## Tips
+
+1. **Use TypeScript** for type safety
+2. **Handle errors** properly
+3. **Use hooks** for custom logic
+4. **Log progress** for visibility
+5. **Use CLI for watch** mode
+6. **Exit on error** in scripts
+
+## Troubleshooting
+
+### Import Errors
+
+Ensure tsdown is installed:
+```bash
+pnpm add -D tsdown
+```
+
+### Type Errors
+
+Import types:
+```ts
+import type { UserConfig } from 'tsdown'
+```
+
+### Build Fails Silently
+
+Add error handling:
+```ts
+try {
+  await build(config)
+} catch (error) {
+  console.error(error)
+  process.exit(1)
+}
+```
+
+### Options Not Working
+
+Check spelling and types:
+```ts
+// ✅ Correct
+{ format: ['esm', 'cjs'] }
+
+// ❌ Wrong
+{ formats: ['esm', 'cjs'] }
+```
+
+## Related
+
+- [Config File](option-config-file.md) - Configuration options
+- [Hooks](advanced-hooks.md) - Lifecycle hooks
+- [CLI](reference-cli.md) - Command-line interface
+- [Plugins](advanced-plugins.md) - Plugin system

package/skills/tsdown/references/advanced-rolldown-options.md

@@ -0,0 +1,117 @@
+# Customizing Rolldown Options
+
+Pass options directly to the underlying Rolldown bundler.
+
+## Overview
+
+tsdown uses [Rolldown](https://rolldown.rs) as its core bundling engine. You can override Rolldown's input and output options directly for fine-grained control.
+
+**Warning:** You should be familiar with Rolldown's behavior before overriding options. Refer to the [Rolldown Config Options](https://rolldown.rs/options/input) documentation.
+
+## Input Options
+
+### Using an Object
+
+```ts
+export default defineConfig({
+  inputOptions: {
+    cwd: './custom-directory',
+  },
+})
+```
+
+### Using a Function
+
+Dynamically modify options based on the output format:
+
+```ts
+export default defineConfig({
+  inputOptions(inputOptions, format) {
+    inputOptions.cwd = './custom-directory'
+    return inputOptions
+  },
+})
+```
+
+## Output Options
+
+### Using an Object
+
+```ts
+export default defineConfig({
+  outputOptions: {
+    legalComments: 'inline',
+  },
+})
+```
+
+### Using a Function
+
+```ts
+export default defineConfig({
+  outputOptions(outputOptions, format) {
+    if (format === 'esm') {
+      outputOptions.legalComments = 'inline'
+    }
+    return outputOptions
+  },
+})
+```
+
+## Common Use Cases
+
+### Preserve Legal Comments
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  outputOptions: {
+    legalComments: 'inline',
+  },
+})
+```
+
+### Custom Working Directory
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  inputOptions: {
+    cwd: './packages/my-lib',
+  },
+})
+```
+
+### Format-Specific Options
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  outputOptions(outputOptions, format) {
+    if (format === 'esm') {
+      outputOptions.legalComments = 'inline'
+    }
+    return outputOptions
+  },
+})
+```
+
+## When to Use
+
+- When tsdown doesn't expose a specific Rolldown option
+- For format-specific Rolldown customizations
+- For advanced bundling scenarios
+
+## Tips
+
+1. **Read Rolldown docs** before overriding options
+2. **Use functions** for format-specific customization
+3. **Test thoroughly** when overriding defaults
+4. **Prefer tsdown options** when available (e.g., use `minify` instead of setting it via `outputOptions`)
+
+## Related
+
+- [Plugins](advanced-plugins.md) - Plugin system
+- [Hooks](advanced-hooks.md) - Lifecycle hooks
+- [Config File](option-config-file.md) - Configuration options

package/skills/tsdown/references/guide-getting-started.md

@@ -0,0 +1,183 @@
+# Getting Started
+
+Quick guide to installing and using tsdown for the first time.
+
+## Installation
+
+Install tsdown as a development dependency:
+
+```bash
+pnpm add -D tsdown
+
+# Optionally install TypeScript if not using isolatedDeclarations
+pnpm add -D typescript
+```
+
+**Requirements:**
+- Node.js 22.18.0 or higher **to run tsdown** (build-time only)
+- Experimental support for Deno and Bun
+
+> [!NOTE]
+> The Node.js 22.18+ requirement only applies to the environment that runs `tsdown` itself. The **bundled output** can target much lower Node.js versions via the [`target`](./option-target.md) option, so libraries built with tsdown are not locked to Node.js 22+ at runtime.
+>
+> If your package needs to support Node.js 18 / 20, the recommended workflow is to **build with Node.js 22+ in CI**, then **test the built output (or the packed tarball) against the lower Node.js versions** you intend to support.
+
+## Quick Start Templates
+
+Use `create-tsdown` CLI for instant setup:
+
+```bash
+pnpm create tsdown@latest
+```
+
+Provides templates for:
+- Pure TypeScript libraries
+- React component libraries
+- Vue component libraries
+- Ready-to-use configurations
+
+## First Bundle
+
+### 1. Create Source Files
+
+```ts
+// src/index.ts
+import { hello } from './hello.ts'
+hello()
+
+// src/hello.ts
+export function hello() {
+  console.log('Hello tsdown!')
+}
+```
+
+### 2. Create Config File
+
+```ts
+// tsdown.config.ts
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+})
+```
+
+### 3. Run Build
+
+```bash
+./node_modules/.bin/tsdown
+```
+
+Output: `dist/index.mjs`
+
+### 4. Test Output
+
+```bash
+node dist/index.mjs
+# Output: Hello tsdown!
+```
+
+## Add to npm Scripts
+
+```json
+{
+  "scripts": {
+    "build": "tsdown"
+  }
+}
+```
+
+Run with:
+
+```bash
+pnpm build
+```
+
+## CLI Commands
+
+```bash
+# Check version
+tsdown --version
+
+# View help
+tsdown --help
+
+# Build with watch mode
+tsdown --watch
+
+# Build with specific format
+tsdown --format esm,cjs
+
+# Generate type declarations
+tsdown --dts
+```
+
+## Basic Configurations
+
+### TypeScript Library (ESM + CJS)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+})
+```
+
+### Browser Library (IIFE)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['iife'],
+  globalName: 'MyLib',
+  platform: 'browser',
+  minify: true,
+})
+```
+
+### Multiple Entry Points
+
+```ts
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    utils: 'src/utils.ts',
+    cli: 'src/cli.ts',
+  },
+  format: ['esm', 'cjs'],
+  dts: true,
+})
+```
+
+## Using Plugins
+
+Add Rolldown, Rollup, or Unplugin plugins:
+
+```ts
+import SomePlugin from 'some-plugin'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  plugins: [SomePlugin()],
+})
+```
+
+## Watch Mode
+
+Enable automatic rebuilds on file changes:
+
+```bash
+tsdown --watch
+# or
+tsdown -w
+```
+
+## Next Steps
+
+- Configure [entry points](option-entry.md) with glob patterns
+- Set up [multiple output formats](option-output-format.md)
+- Enable [type declaration generation](option-dts.md)
+- Explore [plugins](advanced-plugins.md) for extended functionality
+- Read [migration guide](guide-migrate-from-tsup.md) if coming from tsup

package/skills/tsdown/references/guide-introduction.md

@@ -0,0 +1,42 @@
+# Introduction
+
+**tsdown** is _The Elegant Library Bundler_ — a fast, simple bundler for TypeScript and JavaScript libraries powered by Rolldown (Rust-based).
+
+## Why tsdown?
+
+Built on [Rolldown](https://rolldown.rs), tsdown provides a complete out-of-the-box solution for library authors:
+
+- **Simplified Configuration**: Sensible defaults for library development, minimal boilerplate
+- **Library-Specific Features**: Auto TypeScript declarations, multiple output formats, package validation
+- **Future-Ready**: Official Rolldown project, foundation for Rolldown Vite's Library Mode
+
+## Plugin Ecosystem
+
+Supports the full Rolldown plugin ecosystem plus most Rollup plugins. See [Plugins](advanced-plugins.md).
+
+## What Can It Bundle?
+
+- **TypeScript/JavaScript**: `.ts`, `.js` with modern syntax
+- **TypeScript Declarations**: Auto-generate `.d.ts` files
+- **Multiple Formats**: `esm`, `cjs`, `iife`, `umd`
+- **Assets**: `.json`, `.wasm`, CSS files
+- Built-in tree shaking, minification, and source maps
+
+## Key Differences from Rolldown
+
+tsdown wraps Rolldown with library-specific features:
+- Auto-external `dependencies`, `peerDependencies`, and `optionalDependencies` from `package.json`
+- DTS generation
+- `package.json` exports field generation
+- Watch mode with keyboard shortcuts
+- CSS preprocessing pipeline
+- Executable bundling (SEA)
+
+## Prior Arts
+
+Inspired by: Rollup, esbuild, tsup, unbuild. Powered by Rolldown.
+
+## Related
+
+- [Getting Started](guide-getting-started.md) - Installation and first build
+- [Migrate from tsup](guide-migrate-from-tsup.md) - Migration guide