esbuild is a JavaScript bundler written in Go that supports blazing fast ESNext & TypeScript transpilation and JS minification.
esbuild-loader lets you harness the speed of esbuild in your Webpack build by offering faster alternatives for transpilation (eg. babel-loader/ts-loader) and minification (eg. Terser)!
[!TIP]
Are you using TypeScript with Node.js?
Supercharge your Node.js with TypeScript support using tsx!
tsx is a simple, lightweight, and blazing fast alternative to ts-node.
To leverage esbuild-loader in your Webpack configuration, add a new rule for esbuild-loader matching the files you want to transform, such as .js, .jsx, .ts, or .tsx. Make sure to remove any other loaders you were using before (e.g. babel-loader/ts-loader).
Here's an example of how to set it up in your webpack.config.js:
module.exports = { module: { rules: [- // Transpile JavaScript- {- test: /\.js$/,- use: 'babel-loader'- },-- // Compile TypeScript- {- test: /\.tsx?$/,- use: 'ts-loader'- },+ // Use esbuild to compile JavaScript & TypeScript+ {+ // Match `.js`, `.jsx`, `.ts` or `.tsx` files+ test: /\.[jt]sx?$/,+ loader: 'esbuild-loader',+ options: {+ // JavaScript version to compile to+ target: 'es2015'+ }+ }, // Other rules... ], }, }
In this setup, esbuild will automatically determine how to handle each file based on its extension:
.js files will be treated as JS (no JSX allowed)
.jsx as JSX
.ts as TS (no TSX allowed)
.tsx as TSX
If you want to force a specific loader on different file extensions (e.g. to allow JSX in .js files), you can use the loader option:
{ test: /\.js$/, loader: 'esbuild-loader', options: {+ // Treat `.js` files as `.jsx` files+ loader: 'jsx', // JavaScript version to transpile to target: 'es2015' } }
Loader
JavaScript
esbuild-loader can be used in-place of babel-loader to transpile new JavaScript syntax into code compatible with older JavaScript engines.
While this ensures your code can run smoothly across various environments, note that it can bloat your output code (like Babel).
The default target is esnext, which means it doesn't perform any transpilations.
To specify a target JavaScript engine that only supports ES2015, use the following configuration in your webpack.config.js:
esbuild-loader can be used in-place of ts-loader to compile TypeScript.
({ // `.ts` or `.tsx` files test: /\.tsx?$/, loader: 'esbuild-loader'})
[!IMPORTANT]
It's possible to use loader: 'tsx' for both .ts and .tsx files, but this could lead to unexpected behavior as TypeScript and TSX do not have compatible syntaxes.
[!TIP]
The loader's define works with all devtools, including eval-based ones. If you're using the plugin's define and it's not working, try the loader instead.
EsbuildPlugin
Minification
Esbuild supports JavaScript minification, offering a faster alternative to traditional JS minifiers like Terser or UglifyJs. Minification is crucial for reducing file size and improving load times in web development. For a comparative analysis of its performance, refer to these minification benchmarks.
In webpack.config.js:
+ const { EsbuildPlugin } = require('esbuild-loader') module.exports = { ...,+ optimization: {+ minimizer: [+ new EsbuildPlugin({+ target: 'es2015' // Syntax to transpile to (see options below for possible values)+ })+ ]+ }, }
[!TIP]
Utilizing the target option allows for the use of newer JavaScript syntax, enhancing minification effectiveness.
Defining constants
Webpack's DefinePlugin can replaced with EsbuildPlugin to define global constants. This could speed up the build by removing the parsing costs associated with the DefinePlugin.
[!WARNING]
The plugin's define option does not work with eval-based devtools (e.g., eval, eval-source-map). This is because eval devtools wrap module code in eval() strings, and esbuild's define cannot replace identifiers inside string literals. If you need to use define with eval devtools, use the loader's define option instead, which transforms files before bundling.
Transpilation
If your project does not use TypeScript, JSX, or any other syntax that requires additional configuration beyond what Webpack provides, you can use EsbuildPlugin for transpilation instead of the loader.
It will be faster because there's fewer files to process, and will produce a smaller output because polyfills will only be added once for the entire build as opposed to per file.
To utilize esbuild for transpilation, simply set the target option on the plugin to specify which syntax support you want.
CSS Minification
Depending on your setup, there are two ways to minify CSS. You should already have CSS loading setup using css-loader.
CSS assets
If the CSS is extracted and emitted as .css file, you can replace CSS minification plugins like css-minimizer-webpack-plugin with the EsbuildPlugin.
Assuming the CSS is extracted using something like MiniCssExtractPlugin, in webpack.config.js:
If your CSS is not emitted as a .css file, but rather injected with JavaScript using something like style-loader, you can use the loader for minification.
esbuild-loader comes with a version of esbuild it has been tested to work with. However, esbuild has a frequent release cadence, and while we try to keep up with the important releases, it can get outdated.
To work around this, you can use the implementation option in the loader or the plugin to pass in your own version of esbuild (eg. a newer one).
[!WARNING]
⚠esbuild is not stable yet and can have dramatic differences across releases. Using a different version of esbuild is not guaranteed to work.
Replace global identifiers with constant expressions (e.g., 'process.env.NODE_ENV': JSON.stringify('production')).
[!TIP]
Unlike the plugin's define option, the loader's define works with all devtools including eval-based ones (e.g., eval-source-map). This is because the loader transforms files before Webpack bundles them, so identifiers are replaced before any eval wrapping occurs.
The default is iife when esbuild is configured to support a low target, because esbuild injects helper functions at the top of the code. On the web, having functions declared at the top of a script can pollute the global scope. In some cases, this can lead to a variable collision error. By setting format: 'iife', esbuild wraps the helper functions in an IIFE to prevent them from polluting the global.
Whether it's about Webpack configuration, esbuild, or TypeScript, I'm here to guide you every step of the way!
🙋♀️ FAQ
Is it possible to use esbuild plugins?
No. esbuild plugins are only available in the build API. And esbuild-loader uses the transform API instead of the build API for two reasons:
The build API is for creating JS bundles, which is what Webpack does. If you want to use esbuild's build API, consider using esbuild directly instead of Webpack.
The build API reads directly from the file-system, but Webpack loaders operate in-memory. Webpack loaders are essentially just functions that are called with the source-code as the input. Not reading from the file-system allows loaders to be chainable. For example, using vue-loader to compile Single File Components (.vue files), then using esbuild-loader to transpile just the JS part of the SFC.
Running esbuild as a standalone bundler vs esbuild-loader + Webpack are completely different:
esbuild is highly optimized, written in Go, and compiled to native code. Read more about it here.
esbuild-loader is handled by Webpack in a JS runtime, which applies esbuild transforms per file. On top of that, there's likely other loaders & plugins in a Webpack config that slow it down.
Using a JS runtime introduces a bottleneck that makes reaching those speeds impossible. However, esbuild-loader can still speed up your build by removing the bottlenecks created by babel-loader, ts-loader, Terser, etc.