ads-fe 0.0.1

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

@@ -0,0 +1,363 @@
+# Lifecycle Hooks
+
+Extend the build process with lifecycle hooks.
+
+## Overview
+
+Hooks provide a way to inject custom logic at specific stages of the build lifecycle. Inspired by [unbuild](https://github.com/unjs/unbuild).
+
+**Recommendation:** Use [plugins](advanced-plugins.md) for most extensions. Use hooks for simple custom tasks or Rolldown plugin injection.
+
+## Usage Patterns
+
+### Object Syntax
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  hooks: {
+    'build:prepare': async (context) => {
+      console.log('Build starting...')
+    },
+    'build:done': async (context) => {
+      console.log('Build complete!')
+    },
+  },
+})
+```
+
+### Function Syntax
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  hooks(hooks) {
+    hooks.hook('build:prepare', () => {
+      console.log('Preparing build...')
+    })
+
+    hooks.hook('build:before', (context) => {
+      console.log(`Building format: ${context.format}`)
+    })
+  },
+})
+```
+
+## Available Hooks
+
+### `build:prepare`
+
+Called before the build process starts.
+
+**When:** Once per build session
+
+**Context:**
+```ts
+{
+  options: ResolvedConfig,
+  hooks: Hookable
+}
+```
+
+**Use cases:**
+- Setup tasks
+- Validation
+- Environment preparation
+
+**Example:**
+```ts
+hooks: {
+  'build:prepare': async (context) => {
+    console.log('Starting build for:', context.options.entry)
+    await cleanOldFiles()
+  },
+}
+```
+
+### `build:before`
+
+Called before each Rolldown build.
+
+**When:** Once per format (ESM, CJS, etc.)
+
+**Context:**
+```ts
+{
+  options: ResolvedConfig,
+  buildOptions: BuildOptions,
+  hooks: Hookable
+}
+```
+
+**Use cases:**
+- Modify build options per format
+- Inject plugins dynamically
+- Format-specific setup
+
+**Example:**
+```ts
+hooks: {
+  'build:before': async (context) => {
+    console.log(`Building ${context.buildOptions.format} format...`)
+
+    // Add format-specific plugin
+    if (context.buildOptions.format === 'iife') {
+      context.buildOptions.plugins.push(browserPlugin())
+    }
+  },
+}
+```
+
+### `build:done`
+
+Called after the build completes.
+
+**When:** Once per build session
+
+**Context:**
+```ts
+{
+  options: ResolvedConfig,
+  chunks: RolldownChunk[],
+  hooks: Hookable
+}
+```
+
+**Use cases:**
+- Post-processing
+- Asset copying
+- Notifications
+- Deployment
+
+**Example:**
+```ts
+hooks: {
+  'build:done': async (context) => {
+    console.log(`Built ${context.chunks.length} chunks`)
+
+    // Copy additional files
+    await copyAssets()
+
+    // Send notification
+    notifyBuildComplete()
+  },
+}
+```
+
+## Common Patterns
+
+### Build Notifications
+
+```ts
+export default defineConfig({
+  hooks: {
+    'build:prepare': () => {
+      console.log('🚀 Starting build...')
+    },
+    'build:done': (context) => {
+      const size = context.chunks.reduce((sum, c) => sum + c.code.length, 0)
+      console.log(`✅ Build complete! Total size: ${size} bytes`)
+    },
+  },
+})
+```
+
+### Conditional Plugin Injection
+
+```ts
+export default defineConfig({
+  hooks(hooks) {
+    hooks.hook('build:before', (context) => {
+      // Add minification only for production
+      if (process.env.NODE_ENV === 'production') {
+        context.buildOptions.plugins.push(minifyPlugin())
+      }
+    })
+  },
+})
+```
+
+### Custom File Copy
+
+```ts
+import { copyFile } from 'fs/promises'
+
+export default defineConfig({
+  hooks: {
+    'build:done': async (context) => {
+      // Copy README to dist
+      await copyFile('README.md', `${context.options.outDir}/README.md`)
+    },
+  },
+})
+```
+
+### Build Metrics
+
+```ts
+export default defineConfig({
+  hooks: {
+    'build:prepare': (context) => {
+      context.startTime = Date.now()
+    },
+    'build:done': (context) => {
+      const duration = Date.now() - context.startTime
+      console.log(`Build took ${duration}ms`)
+
+      // Log chunk sizes
+      context.chunks.forEach((chunk) => {
+        console.log(`${chunk.fileName}: ${chunk.code.length} bytes`)
+      })
+    },
+  },
+})
+```
+
+### Format-Specific Logic
+
+```ts
+export default defineConfig({
+  format: ['esm', 'cjs', 'iife'],
+  hooks: {
+    'build:before': (context) => {
+      const format = context.buildOptions.format
+
+      if (format === 'iife') {
+        // Browser-specific setup
+        context.buildOptions.globalName = 'MyLib'
+      } else if (format === 'cjs') {
+        // Node-specific setup
+        context.buildOptions.platform = 'node'
+      }
+    },
+  },
+})
+```
+
+### Deployment Hook
+
+```ts
+export default defineConfig({
+  hooks: {
+    'build:done': async (context) => {
+      if (process.env.DEPLOY === 'true') {
+        console.log('Deploying to CDN...')
+        await deployToCDN(context.options.outDir)
+      }
+    },
+  },
+})
+```
+
+## Advanced Usage
+
+### Multiple Hooks
+
+```ts
+export default defineConfig({
+  hooks(hooks) {
+    // Register multiple hooks
+    hooks.hook('build:prepare', setupEnvironment)
+    hooks.hook('build:prepare', validateConfig)
+
+    hooks.hook('build:before', injectPlugins)
+    hooks.hook('build:before', logFormat)
+
+    hooks.hook('build:done', generateManifest)
+    hooks.hook('build:done', notifyComplete)
+  },
+})
+```
+
+### Async Hooks
+
+```ts
+export default defineConfig({
+  hooks: {
+    'build:prepare': async (context) => {
+      await fetchRemoteConfig()
+      await initializeDatabase()
+    },
+    'build:done': async (context) => {
+      await uploadToS3(context.chunks)
+      await invalidateCDN()
+    },
+  },
+})
+```
+
+### Error Handling
+
+```ts
+export default defineConfig({
+  hooks: {
+    'build:done': async (context) => {
+      try {
+        await riskyOperation()
+      } catch (error) {
+        console.error('Hook failed:', error)
+        // Don't throw - allow build to complete
+      }
+    },
+  },
+})
+```
+
+## Hookable API
+
+tsdown uses [hookable](https://github.com/unjs/hookable) for hooks. Additional methods:
+
+```ts
+export default defineConfig({
+  hooks(hooks) {
+    // Register hook
+    hooks.hook('build:done', handler)
+
+    // Register hook once
+    hooks.hookOnce('build:prepare', handler)
+
+    // Remove hook
+    hooks.removeHook('build:done', handler)
+
+    // Clear all hooks for event
+    hooks.removeHooks('build:done')
+
+    // Call hooks manually
+    await hooks.callHook('build:done', context)
+  },
+})
+```
+
+## Tips
+
+1. **Use plugins** for most extensions
+2. **Hooks for simple tasks** like notifications or file copying
+3. **Async hooks supported** for I/O operations
+4. **Don't throw errors** unless you want to fail the build
+5. **Context is mutable** in `build:before` for advanced use cases
+6. **Multiple hooks allowed** for the same event
+
+## Troubleshooting
+
+### Hook Not Called
+
+- Verify hook name is correct
+- Check hook is registered in config
+- Ensure async hooks are awaited
+
+### Build Fails in Hook
+
+- Add try/catch for error handling
+- Don't throw unless intentional
+- Log errors for debugging
+
+### Context Undefined
+
+- Check which hook you're using
+- Verify context properties available for that hook
+
+## Related
+
+- [Plugins](advanced-plugins.md) - Plugin system
+- [Rolldown Options](advanced-rolldown-options.md) - Build options
+- [Watch Mode](option-watch-mode.md) - Development workflow

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

@@ -0,0 +1,381 @@
+# Plugins
+
+Extend tsdown with plugins from multiple ecosystems.
+
+## Overview
+
+tsdown, built on Rolldown, supports plugins from multiple ecosystems to extend and customize the bundling process.
+
+## Supported Ecosystems
+
+### 1. Rolldown Plugins
+
+Native plugins designed for Rolldown:
+
+```ts
+import RolldownPlugin from 'rolldown-plugin-something'
+
+export default defineConfig({
+  plugins: [RolldownPlugin()],
+})
+```
+
+**Compatibility:** ✅ Full support
+
+### 2. Unplugin
+
+Universal plugins that work across bundlers:
+
+```ts
+import UnpluginPlugin from 'unplugin-something'
+
+export default defineConfig({
+  plugins: [UnpluginPlugin.rolldown()],
+})
+```
+
+**Compatibility:** ✅ Most unplugin-* plugins work
+
+**Examples:**
+- `unplugin-vue-components`
+- `unplugin-auto-import`
+- `unplugin-icons`
+
+### 3. Rollup Plugins
+
+Most Rollup plugins work with tsdown:
+
+```ts
+import RollupPlugin from '@rollup/plugin-something'
+
+export default defineConfig({
+  plugins: [RollupPlugin()],
+})
+```
+
+**Compatibility:** ✅ High compatibility
+
+**Type Issues:** May cause TypeScript errors - use type casting:
+
+```ts
+import RollupPlugin from 'rollup-plugin-something'
+
+export default defineConfig({
+  plugins: [
+    // @ts-expect-error Rollup plugin type mismatch
+    RollupPlugin(),
+    // Or cast to any
+    RollupPlugin() as any,
+  ],
+})
+```
+
+### 4. Vite Plugins
+
+Some Vite plugins may work:
+
+```ts
+import VitePlugin from 'vite-plugin-something'
+
+export default defineConfig({
+  plugins: [
+    // @ts-expect-error Vite plugin type mismatch
+    VitePlugin(),
+  ],
+})
+```
+
+**Compatibility:** ⚠️ Limited - only if not using Vite-specific APIs
+
+**Note:** Improved support planned for future releases.
+
+## Usage
+
+### Basic Plugin Usage
+
+```ts
+import { defineConfig } from 'tsdown'
+import SomePlugin from 'some-plugin'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  plugins: [SomePlugin()],
+})
+```
+
+### Multiple Plugins
+
+```ts
+import PluginA from 'plugin-a'
+import PluginB from 'plugin-b'
+import PluginC from 'plugin-c'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  plugins: [
+    PluginA(),
+    PluginB({ option: true }),
+    PluginC(),
+  ],
+})
+```
+
+### Conditional Plugins
+
+```ts
+export default defineConfig((options) => ({
+  entry: ['src/index.ts'],
+  plugins: [
+    SomePlugin(),
+    options.watch && DevPlugin(),
+    !options.watch && ProdPlugin(),
+  ].filter(Boolean),
+}))
+```
+
+## Common Plugin Patterns
+
+### JSON Import
+
+```ts
+import json from '@rollup/plugin-json'
+
+export default defineConfig({
+  plugins: [json()],
+})
+```
+
+### Node Resolve
+
+```ts
+import { nodeResolve } from '@rollup/plugin-node-resolve'
+
+export default defineConfig({
+  plugins: [nodeResolve()],
+})
+```
+
+### CommonJS
+
+```ts
+import commonjs from '@rollup/plugin-commonjs'
+
+export default defineConfig({
+  plugins: [commonjs()],
+})
+```
+
+### Replace
+
+```ts
+import replace from '@rollup/plugin-replace'
+
+export default defineConfig({
+  plugins: [
+    replace({
+      'process.env.NODE_ENV': JSON.stringify('production'),
+      __VERSION__: JSON.stringify('1.0.0'),
+    }),
+  ],
+})
+```
+
+### Auto Import
+
+```ts
+import AutoImport from 'unplugin-auto-import/rolldown'
+
+export default defineConfig({
+  plugins: [
+    AutoImport({
+      imports: ['vue', 'vue-router'],
+      dts: 'src/auto-imports.d.ts',
+    }),
+  ],
+})
+```
+
+### Vue Components
+
+```ts
+import Components from 'unplugin-vue-components/rolldown'
+
+export default defineConfig({
+  plugins: [
+    Components({
+      dts: 'src/components.d.ts',
+    }),
+  ],
+})
+```
+
+## Framework-Specific Plugins
+
+### React
+
+```ts
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  entry: ['src/index.tsx'],
+  plugins: [
+    // @ts-expect-error Vite plugin
+    react(),
+  ],
+})
+```
+
+### Vue
+
+```ts
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  plugins: [
+    // @ts-expect-error Vite plugin
+    vue(),
+  ],
+})
+```
+
+### Solid
+
+```ts
+import solid from 'vite-plugin-solid'
+
+export default defineConfig({
+  entry: ['src/index.tsx'],
+  plugins: [
+    // @ts-expect-error Vite plugin
+    solid(),
+  ],
+})
+```
+
+### Svelte
+
+```ts
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  plugins: [
+    // @ts-expect-error Vite plugin
+    svelte(),
+  ],
+})
+```
+
+## Writing Custom Plugins
+
+Follow Rolldown's plugin development guide:
+
+### Basic Plugin Structure
+
+```ts
+import type { Plugin } from 'rolldown'
+
+function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',
+
+    // Transform hook
+    transform(code, id) {
+      if (id.endsWith('.custom')) {
+        return {
+          code: transformCode(code),
+          map: null,
+        }
+      }
+    },
+
+    // Other hooks...
+  }
+}
+```
+
+### Using Custom Plugin
+
+```ts
+import { myPlugin } from './my-plugin'
+
+export default defineConfig({
+  plugins: [myPlugin()],
+})
+```
+
+## Plugin Configuration
+
+### Plugin-Specific Options
+
+Refer to each plugin's documentation for configuration options.
+
+### Plugin Order
+
+Plugins run in the order they're defined:
+
+```ts
+export default defineConfig({
+  plugins: [
+    PluginA(),  // Runs first
+    PluginB(),  // Runs second
+    PluginC(),  // Runs last
+  ],
+})
+```
+
+## Troubleshooting
+
+### Type Errors with Rollup/Vite Plugins
+
+Use type casting:
+
+```ts
+plugins: [
+  // Option 1: @ts-expect-error
+  // @ts-expect-error Plugin type mismatch
+  SomePlugin(),
+
+  // Option 2: as any
+  SomePlugin() as any,
+]
+```
+
+### Plugin Not Working
+
+1. **Check compatibility** - Verify plugin supports your bundler
+2. **Read documentation** - Follow plugin's setup instructions
+3. **Check plugin order** - Some plugins depend on execution order
+4. **Enable debug mode** - Use `--debug` flag
+
+### Vite Plugin Fails
+
+Vite plugins may rely on Vite-specific APIs:
+
+1. **Find Rollup equivalent** - Look for Rollup version of plugin
+2. **Use Unplugin version** - Check for `unplugin-*` alternative
+3. **Wait for support** - Vite plugin support improving
+
+## Resources
+
+- [Rolldown Plugin Development](https://rolldown.rs/apis/plugin-api)
+- [Unplugin Documentation](https://unplugin.unjs.io/)
+- [Rollup Plugins](https://github.com/rollup/plugins)
+- [Vite Plugins](https://vitejs.dev/plugins/)
+
+## Tips
+
+1. **Prefer Rolldown plugins** for best compatibility
+2. **Use Unplugin** for cross-bundler support
+3. **Cast types** for Rollup/Vite plugins
+4. **Test thoroughly** when using cross-ecosystem plugins
+5. **Check plugin docs** for specific configuration
+6. **Write custom plugins** for unique needs
+
+## Related
+
+- [Hooks](advanced-hooks.md) - Lifecycle hooks
+- [Rolldown Options](advanced-rolldown-options.md) - Advanced Rolldown config
+- [React Recipe](recipe-react.md) - React setup with plugins
+- [Vue Recipe](recipe-vue.md) - Vue setup with plugins