esbuild-extra
v0.4.0
Published
Extra features for esbuild plugins
Downloads
1,119
Maintainers
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 ofonResolve
resultsload
build method for loading a file viaonLoad
andonTransform
hooksemitChunk
andemitFile
build methods for dynamically generated outputsresolveLocallyFirst
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 and ~6 MB here).
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.
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).
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 anonTransform
hook, it will be applied to every compatible file regardless of the file's namespace. You can usenamespace: "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 anyonTransform
hooks targeting those specific extensions are applied and also after the file is transpiled to plain JavaScript. Similarly, this works foronTransform
hooks targeting.jsx
files or.ts
files (both applied to.tsx
files after transpilation).
Prior art
License
MIT