esbuild-plugin-pipe

0.2.0 verified Fri May 01 auth: no javascript

A tiny esbuild plugin (v0.2.0) that composes other esbuild plugins by piping their output sequentially, analogous to Unix pipes. Release cadence is low (last release 2021). It requires plugins to explicitly opt-in to support piping, which limits compatibility. Alternative approaches include manually chaining onLoad callbacks or using `esbuild`'s built-in plugin ordering. Only 84 bytes minified.

Common errors

error Error: The transform argument is not an object. Expected { contents, args } but got ... ↓

cause Using pipe() with a plugin that does not comply with the v0.2.0 protocol where transform is an object parameter.

fix

Update the plugin to use setup(build, { transform } = {}) and handle transform.contents and transform.args.

error TypeError: Cannot read properties of undefined (reading 'contents') ↓

cause The plugin's setup function tries to access transform.contents without checking if transform is defined.

fix

Guard with if (transform) before accessing transform.contents.

Warnings

breaking In v0.2.0, the transform argument to setup() changed from a direct parameter to an object property: setup(build, { transform }) instead of setup(build, transform). ↓

fix Update plugin setup functions to destructure transform from the second argument: setup(build, { transform } = {}).

gotcha Plugins must explicitly support piping by checking the transform argument; otherwise pipe() silently ignores them and passes through unmodified contents. ↓

fix Only use pipe() with plugins that implement the piping protocol as documented.

gotcha The plugin only supports piping onLoad callbacks; it does not affect other hooks like onResolve or onStart. ↓

fix For other hooks, chain plugins manually or use a different composition mechanism.

Install

npm install esbuild-plugin-pipe

yarn add esbuild-plugin-pipe

pnpm add esbuild-plugin-pipe

Imports

default

wrong

const pipe = require('esbuild-plugin-pipe')

correct

import pipe from 'esbuild-plugin-pipe'

ESM-only; CommonJS require will fail.

pipe (named)
wrong
```
import pipe from 'esbuild-plugin-pipe'
```
correct
```
import { pipe } from 'esbuild-plugin-pipe'
```
Both default and named exports work; default export is recommended.

config type

wrong

type PipeOptions = { filter: RegExp; namespace: string; plugins: any[] }

correct

interface PipeOptions { filter?: RegExp; namespace?: string; plugins: import('esbuild').Plugin[] }

Uses esbuild's Plugin type for type safety.

Quickstart

Shows basic usage of esbuild-plugin-pipe to transform file contents sequentially.

import esbuild from 'esbuild';
import pipe from 'esbuild-plugin-pipe';

await esbuild.build({
  entryPoints: ['input.js'],
  bundle: true,
  outfile: 'output.js',
  plugins: [
    pipe({
      filter: /\.js$/,
      namespace: 'file',
      plugins: [
        {
          name: 'example',
          setup(build, { transform } = {}) {
            if (transform) {
              transform.contents = transform.contents.toUpperCase();
              return { contents: transform.contents };
            }
            build.onLoad({ filter: /.*/ }, async (args) => {
              const fs = await import('fs/promises');
              let contents = await fs.readFile(args.path, 'utf8');
              contents = contents.toUpperCase();
              return { contents };
            });
          }
        }
      ]
    })
  ]
}).catch(() => process.exit(1));