esbuild-plugin-merge

1.0.7 verified Fri May 01 auth: no javascript deprecated

Merge esbuild plugins and provide Rollup-like features (watchChange, transform, enforce, pre). Current stable version 1.0.7. No active maintenance; incompatible with esbuild >=0.17. Designed for projects that need plugin ordering (enforce), transform hooks similar to Rollup/Vite, and watch updates. Key differentiator: adds `onTransform` and `onUpdate` hooks to esbuild's standard onResolve/onLoad.

Common errors

error Error: Cannot find module 'esbuild-plugin-merge' ↓

cause Package not installed or not installed in the project.

fix

npm install esbuild-plugin-merge

error TypeError: merge is not a function ↓

cause Using CommonJS require() instead of ESM import.

fix

Use import { merge } from 'esbuild-plugin-merge' in an ESM context.

error Error: Build failed with 1 error: error: Invalid plugin: onTransform or onUpdate hooks are not supported in esbuild >= 0.17.0 ↓

cause esbuild version >=0.17.0; hooks removed.

fix

Downgrade esbuild to 0.16.x or use alternative plugin.

Warnings

breaking Incompatible with esbuild >=0.17.0. The plugin API changed; `onTransform` and `onUpdate` rely on removed internal hooks. ↓

fix Downgrade esbuild to 0.16.x or switch to another plugin merging approach.

gotcha `pre` wrapper expects a standard esbuild Plugin, not a ProPlugin. Wrapping a ProPlugin with `pre` may cause unexpected behavior. ↓

fix Only use `pre()` on esbuild.Plugin objects, not on ProPlugin.

gotcha `onTransform` returns undefined; the returned object from the hook is ignored. Mutation of `loadres` is the intended use. ↓

fix Do not return a new object from onTransform; mutate `loadres` directly.

deprecated Package is unmaintained. Last update 2022. No support for esbuild 0.17+ or later. ↓

fix Consider using esbuild's native plugin capabilities or other community plugins.

Install

npm install esbuild-plugin-merge

yarn add esbuild-plugin-merge

pnpm add esbuild-plugin-merge

Imports

merge

wrong

const { merge } = require('esbuild-plugin-merge')

correct

import { merge } from 'esbuild-plugin-merge'

ESM-only; does not support CommonJS require.

pre

wrong

const pre = require('esbuild-plugin-merge').pre

correct

import { pre } from 'esbuild-plugin-merge'

pre wraps a standard esbuild plugin to add sorting support.

ProPlugin

wrong

import { ProPlugin } from 'esbuild-plugin-merge'

correct

import type { ProPlugin } from 'esbuild-plugin-merge'

ProPlugin is a TypeScript type, not a runtime value. Use type import.

Quickstart

Shows how to use merge() to combine plugins, pre() for ordering, and ProPlugin for transform hook.

import { merge, pre, ProPlugin } from 'esbuild-plugin-merge';
import * as esbuild from 'esbuild';

const pluginA: ProPlugin = {
  name: 'pluginA',
  enforce: 'post',
  setup(build) {
    build.onTransform({ filter: /\.css/ }, (loadres, args) => {
      // transform hook like Rollup
      loadres.code = loadres.code.replace(/\/\*.*?\*\//g, '');
      return loadres;
    });
  },
};

const pluginB: esbuild.Plugin = {
  name: 'pluginB',
  setup(build) {
    build.onResolve({ filter: /\.svg/ }, (args) => ({ path: args.path }));
  },
};

async function main() {
  const result = await esbuild.build({
    entryPoints: ['src/index.ts'],
    bundle: true,
    outfile: 'dist/out.js',
    plugins: [merge([pluginA, pre(pluginB)])],
  });
  console.log('Build succeeded');
}

main().catch(console.error);