complugin

1.1.4 verified Fri May 01 auth: no javascript maintenance

Unified plugin system for multiple bundlers (Rollup, Vite, Webpack, esbuild) using a common plugin API based on Rollup's hook model. Current stable version 1.1.4. Allows writing one plugin that works across bundlers with bundler-specific adapters. Key differentiator: developers maintain one codebase instead of separate plugins per tool. Ships TypeScript types. Peer dependencies include specific versions of each bundler. Release cadence is irregular; last update August 2022. Note: esbuild requires proxyEsbuild wrapper; Webpack must avoid thread-loader; Rollup disallows as output plugin.

Common errors

error Error: [complugin] proxyEsbuild must be called before esbuild.build ↓

cause Using esbuild.build() directly without calling proxyEsbuild first.

fix

Import and call proxyEsbuild: import { proxyEsbuild } from 'complugin'; const esbuild = proxyEsbuild(originalEsbuild); esbuild.build({ plugins: [...] })

error TypeError: myPlugin.vite is not a function ↓

cause Importing the plugin incorrectly (e.g., missing .default or using wrong import style).

fix

Use named import of the exported function and call it with options: import myPlugin from './my-plugin'; myPlugin.vite({...})

error Module parse failed: Unexpected token (1:0) in webpack with thread-loader ↓

cause Using thread-loader in Webpack together with complugin causes parsing errors.

fix

Remove thread-loader from webpack configuration.

Warnings

breaking In Webpack, thread-loader is incompatible with complugin. Do not use thread-loader in the same compilation. ↓

fix Remove thread-loader from webpack configuration or avoid using it with complugin plugins.

breaking In Rollup, complugin cannot be used as an output plugin. Only input plugins are supported. ↓

fix Place the plugin in the plugins array of the input options, not in output.plugins.

breaking In esbuild, you must proxy esbuild via proxyEsbuild(originalEsbuild) before using complugin plugins. Using original esbuild.build() will not apply the plugins. ↓

fix const esbuild = proxyEsbuild(require('esbuild')); esbuild.build({ plugins: [...] })

gotcha Plugin functions created by createComplugin return an object with bundler-specific methods (.vite, .rollup, .webpack, .esbuild). They are not directly passable as plugins without calling the method. ↓

fix Always call the appropriate method: myPlugin.vite(options) or myPlugin(options).vite

Install

npm install complugin

yarn add complugin

pnpm add complugin

Imports

createComplugin
wrong
```
const { createComplugin } = require('complugin')
```
correct
```
import { createComplugin } from 'complugin'
```
ESM-only; no default export, named import required. TypeScript types included.
proxyEsbuild
wrong
```
import proxyEsbuild from 'complugin'
```
correct
```
import { proxyEsbuild } from 'complugin'
```
Named export; required for esbuild integration when using esbuild plugin.
default export from plugin
wrong
```
const MyPlugin = require('./my-plugin').default;
```
correct
```
import MyPlugin from './my-plugin'; MyPlugin.vite(options);
```
Plugins created with createComplugin export a function that returns an object with .vite, .rollup, .webpack, .esbuild methods. In Webpack CJS, use .default.

Quickstart

Creates a simple transform plugin that prepends a prefix to JS files, then uses it in Rollup.

import { createComplugin } from 'complugin'

const myPlugin = createComplugin<{ prefix?: string }>({
  name: 'my-plugin',
  factory(options, meta) {
    return {
      transform(code, id) {
        if (!id.endsWith('.js')) return null
        return {
          code: `${options.prefix || ''}${code}`,
          map: null
        }
      }
    }
  }
})

// Rollup usage
import { rollup } from 'rollup'
const bundle = await rollup({
  input: 'src/index.js',
  plugins: [myPlugin.rollup({ prefix: '// prepended\n' })]
})