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

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:

import RolldownPlugin from 'rolldown-plugin-something'

export default defineConfig({
  plugins: [RolldownPlugin()],
})

Compatibility: ✅ Full support

2. Unplugin

Universal plugins that work across bundlers:

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:

import RollupPlugin from '@rollup/plugin-something'

export default defineConfig({
  plugins: [RollupPlugin()],
})

Compatibility: ✅ High compatibility

Type Issues: May cause TypeScript errors - use type casting:

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:

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

import { defineConfig } from 'tsdown'
import SomePlugin from 'some-plugin'

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [SomePlugin()],
})

Multiple Plugins

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

export default defineConfig((options) => ({
  entry: ['src/index.ts'],
  plugins: [
    SomePlugin(),
    options.watch && DevPlugin(),
    !options.watch && ProdPlugin(),
  ].filter(Boolean),
}))

Common Plugin Patterns

JSON Import

import json from '@rollup/plugin-json'

export default defineConfig({
  plugins: [json()],
})

Node Resolve

import { nodeResolve } from '@rollup/plugin-node-resolve'

export default defineConfig({
  plugins: [nodeResolve()],
})

CommonJS

import commonjs from '@rollup/plugin-commonjs'

export default defineConfig({
  plugins: [commonjs()],
})

Replace

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

import AutoImport from 'unplugin-auto-import/rolldown'

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vue', 'vue-router'],
      dts: 'src/auto-imports.d.ts',
    }),
  ],
})

Vue Components

import Components from 'unplugin-vue-components/rolldown'

export default defineConfig({
  plugins: [
    Components({
      dts: 'src/components.d.ts',
    }),
  ],
})

Framework-Specific Plugins

React

import react from '@vitejs/plugin-react'

export default defineConfig({
  entry: ['src/index.tsx'],
  plugins: [
    // @ts-expect-error Vite plugin
    react(),
  ],
})

Vue

import vue from '@vitejs/plugin-vue'

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [
    // @ts-expect-error Vite plugin
    vue(),
  ],
})

Solid

import solid from 'vite-plugin-solid'

export default defineConfig({
  entry: ['src/index.tsx'],
  plugins: [
    // @ts-expect-error Vite plugin
    solid(),
  ],
})

Svelte

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

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

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:

export default defineConfig({
  plugins: [
    PluginA(),  // Runs first
    PluginB(),  // Runs second
    PluginC(),  // Runs last
  ],
})

Troubleshooting

Type Errors with Rollup/Vite Plugins

Use type casting:

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
• Unplugin Documentation
• Rollup Plugins
• Vite 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 - Lifecycle hooks
• Rolldown Options - Advanced Rolldown config
• React Recipe - React setup with plugins
• Vue Recipe - Vue setup with plugins