esbuild-extra

0.4.2 verified Mon Apr 27 auth: no javascript

A lightweight utility library (0.4.2) that extends esbuild plugins with onTransform, onResolved, load, emitChunk, emitFile, and resolveLocallyFirst features. It is ~6x smaller than @chialab/esbuild-rna and provides TypeScript types. Key differentiators: cooperative onTransform with sourcemap support, namespace-aware hook ordering, and minimal footprint. Suitable for plugin authors wanting extra build hooks without heavy dependencies. Compatible with esbuild >=0.15. Version 0.4 released 2023.

Common errors

error Error: No matching export for import "wrapPlugins" from "esbuild-extra" ↓

cause Using default import style on a named export.

fix

Use { wrapPlugins } in the import statement.

error TypeError: getBuildExtensions is not a function ↓

cause Possibly importing wrong symbol or using old version that didn't export it (added in 0.3).

fix

Check version: run 'npm ls esbuild-extra' and upgrade if <0.3. Use named import: import { getBuildExtensions } from 'esbuild-extra'.

error Cannot find module 'esbuild-extra/global' or its corresponding type declarations. ↓

cause The ambient module augmentation file is not included in tsconfig or the path is wrong.

fix

Ensure your tsconfig includes esbuild-extra types. If not, add 'esbuild-extra' to types array or install @types/esbuild-extra (though it ships its own).

Warnings

gotcha onTransform hooks apply to files matching loaders or extensions, and ordering matters. Hooks for specific extensions (e.g., .tsx) run before general ones (e.g., .js). ↓

fix Define hooks with most specific extension first, or use namespace to limit scope.

gotcha getBuildExtensions must be called with a unique namespace string per plugin; using the same namespace for multiple plugins can cause conflicts. ↓

fix Pass a unique name (e.g., plugin name) as second argument to getBuildExtensions.

breaking In esbuild-extra <0.4, onTransform hooks were not applied to .jsx/.ts files after transpilation. Version 0.4 added automatic extension propagation. ↓

fix Update to >=0.4 or manually handle extension chains.

Install

npm install esbuild-extra

yarn add esbuild-extra

pnpm add esbuild-extra

Imports

wrapPlugins

wrong

import wrapPlugins from 'esbuild-extra'

correct

import { wrapPlugins } from 'esbuild-extra'

wrapPlugins is a named export, not default.

getBuildExtensions

wrong

const { getBuildExtensions } = require('esbuild-extra')

correct

import { getBuildExtensions } from 'esbuild-extra'

CommonJS require works but TypeScript may need esModuleInterop.

Types PluginBuild extensions
wrong
```
import { global } from 'esbuild-extra'
```
correct
```
import 'esbuild-extra/global'
```
Side-effect import in .d.ts file to augment PluginBuild types; no need to import from package.

Quickstart

Shows how to use wrapPlugins to enable extended features for all plugins.

import { wrapPlugins } from 'esbuild-extra';
import * as esbuild from 'esbuild';

async function build() {
  let plugins = []; // your plugins
  let options = {
    entryPoints: ['app.ts'],
    bundle: true,
    outdir: 'dist',
    plugins: plugins,
  };
  options = wrapPlugins(options);
  await esbuild.build(options);
}

build().catch(console.error);