# esbuild-extra

> Extra features for esbuild plugins

Latest version **0.4.2** (published 2025-04-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install esbuild-extra
pnpm add esbuild-extra
yarn add esbuild-extra
bun add esbuild-extra
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.2 |
| Published | 2025-04-01 |
| First published | 2023-03-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 35.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17 |
| Author | Alec Larson |
| Maintainers | aleclarson |
| Keywords | esbuild, plugin, extra, transform, emit |

## Links

- npm: https://www.npmjs.com/package/esbuild-extra
- Repository: https://github.com/aleclarson/esbuild-extra
- Homepage: https://github.com/aleclarson/esbuild-extra#readme
- Issues: https://github.com/aleclarson/esbuild-extra/issues
- npm.io page: https://npm.io/package/esbuild-extra

## Dependencies (4)

- [tsconfck](https://npm.io/package/tsconfck.md) ^2.1.1
- [enhanced-resolve](https://npm.io/package/enhanced-resolve.md) ^5.15.0
- [convert-source-map](https://npm.io/package/convert-source-map.md) ^2.0.0
- [@ampproject/remapping](https://npm.io/package/@ampproject/remapping.md) ^2.2.1

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 0.4.2 (latest) — 2025-04-01
- 0.4.1 — 2025-04-01
- 0.4.0 — 2024-04-20
- 0.3.1 — 2023-07-12
- 0.3.0 — 2023-07-10
- 0.2.1 — 2023-05-13
- 0.2.0 — 2023-05-12
- 0.1.10 — 2023-04-17
- 0.1.9 — 2023-04-17
- 0.1.8 — 2023-04-16
- 0.1.7 — 2023-04-16
- 0.1.6 — 2023-04-16
- 0.1.5 — 2023-04-16
- 0.1.4 — 2023-04-15
- 0.1.3 — 2023-03-22
- … 3 more at https://npm.io/package/esbuild-extra/versions

## README

# esbuild-extra

The lighter alternative to `@chialab/esbuild-rna` that extends `esbuild` plugins with the following new features:

- `onTransform` build hook for co-operative file transformation (with sourcemap support)
- `onResolved` build hook for manipulation of `onResolve` results
- `load` build method for loading a file via `onLoad` and `onTransform` hooks
- `emitChunk` and `emitFile` build methods for dynamically generated outputs
- `resolveLocallyFirst` build method for path resolution where local files are preferred, but plugin-resolved paths are used otherwise

That's it, for now!

This package is ~6x smaller than `@chialab/esbuild-rna` according to PackagePhobia (see ~1 MB [here](https://packagephobia.com/result?p=esbuild-extra) and ~6 MB [here](https://packagephobia.com/result?p=%40chialab%2Fesbuild-rna)).

## Usage

Apart from TypeScript typings, the only exports are `wrapPlugins` and `getBuildExtensions`.

The `wrapPlugins` function can be used by build tools to provide the features of `esbuild-extra` to every esbuild plugin. In this case, I also recommend importing `esbuild-extra/global` inan ambient `.d.ts` file to transparently propagate our `PluginBuild` extensions to downstream TypeScript users.

```ts
import { wrapPlugins } from 'esbuild-extra'

// It returns a new object where everything is identical except the plugins are wrapped!
esbuildOptions = wrapPlugins(esbuildOptions)
```

If you're writing a standalone esbuild plugin, you'll want to use `getBuildExtensions` instead. Just note that your plugin won't play nicely with other plugins with `onLoad` hooks if they don't also use this package (but everything works fine if the other plugin isn't trying to load the files you want to transform).

```ts
import { getBuildExtensions } from 'esbuild-extra'

export default {
  name: 'my-esbuild-plugin',
  setup(build) {
    const { onTransform } = getBuildExtensions(build, 'my-esbuild-plugin')

    onTransform({ loaders: ['tsx'] }, async args => {
      // Transform args.code and return a { code, map } object when you're ready!
    })
  },
}
```

### onTransform hooks

Here are some tips about the `onTransform` feature.

- If no `namespace` is defined for an `onTransform` hook, it will be applied to every compatible file regardless of the file's namespace. You can use `namespace: "file"` to only affect real files without a custom namespace.

- If an `onTransform` hook is targeted at `.js` files, it will also be applied to `.jsx`, `.ts`, and `.tsx` files, but only after any `onTransform` hooks targeting those specific extensions are applied and also after the file is transpiled to plain JavaScript. Similarly, this works for `onTransform` hooks targeting `.jsx` files or `.ts` files (both applied to `.tsx` files after transpilation).

## Prior art

- [@chialab/esbuild-rna](https://github.com/chialab/rna/tree/main/packages/esbuild-rna)

## License

MIT

---
_Source: https://npm.io/package/esbuild-extra · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._