chore: consolidate new foundation and archive v1 (#1495)

2026-09-07 12:32:57 -05:00
parent 9a5fbdbda7 5d27700026
commit 127a54fdff
3511 changed files with 727899 additions and 10 deletions
@@ -0,0 +1,376 @@
+# 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/guide/plugin-development)
+- [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