esbuild-loader is a Webpack loader that leverages the esbuild bundler to perform fast JavaScript and TypeScript transpilation and bundling. It is designed to significantly speed up the build process by using esbuild's highly optimized and parallelized architecture.
What are esbuild-loader's main functionalities?
JavaScript and TypeScript Transpilation
This feature allows you to transpile JavaScript and TypeScript files using esbuild. The code sample demonstrates how to configure esbuild-loader in a Webpack configuration to handle `.tsx` and `.ts` files, targeting ES2015 syntax.
module.exports = {
module: {
rules: [
{
test: /\.tsx?$/,
loader: 'esbuild-loader',
options: {
loader: 'tsx', // Or 'ts' if you don't need tsx
target: 'es2015' // Syntax to compile to (see options below for possible values)
}
}
]
}
};
Minification
esbuild-loader can also be used to minify JavaScript code. The code sample shows how to use the `EsbuildPlugin` to enable minification in a Webpack configuration, targeting ES2015 syntax.
const EsbuildPlugin = require('esbuild-loader').EsbuildPlugin;
module.exports = {
optimization: {
minimize: true,
minimizer: [
new EsbuildPlugin({
target: 'es2015' // Syntax to compile to (see options below for possible values)
})
]
}
};
CSS Loading
esbuild-loader can also handle CSS files. The code sample demonstrates how to configure esbuild-loader to load and minify CSS files in a Webpack configuration.
babel-loader is a Webpack loader that uses Babel to transpile JavaScript and TypeScript files. While babel-loader is highly configurable and supports a wide range of plugins and presets, it is generally slower than esbuild-loader due to Babel's single-threaded architecture.
ts-loader is a Webpack loader specifically designed for TypeScript transpilation using the TypeScript compiler (tsc). It provides fine-grained control over TypeScript compilation but is slower compared to esbuild-loader, which uses esbuild's faster, parallelized architecture.
terser-webpack-plugin is a Webpack plugin used for minifying JavaScript files using Terser. While it is highly configurable and widely used, it is generally slower than esbuild-loader's minification capabilities, which leverage esbuild's optimized performance.
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)!
If you're interested in supercharging your Node.js runtime with esbuild, take a look at our new project tsx. It's an esbuild-enhanced Node.js runtime that can run TypeScript instantly!
🚀 Install
npm i -D esbuild-loader
🚦 Quick Setup
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 & .tsx files as JSX
.ts as TS (no JSX allowed)
.tsx as TSX
If you want to force a specific handler 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
You can replace babel-loader with esbuild-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).
By default, the target to 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:
You can replace JS minifiers like Terser or UglifyJs. Checkout the benchmarks to see how much faster esbuild is. The target option tells esbuild that it can use newer JS syntax to perform better minification.
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)+ })+ ]+ },
}
Defining constants
You can replace the DefinePlugin to define global constants. The parsing cost of the DefinePlugin is often overlooked so replacing it with esbuild can speed up the build.
If you're not using TypeScript, JSX, or any syntax unsupported by Webpack, you can also leverage the minifier for transpilation (as an alternative to Babel).
It will be faster because there's less files to work on and will produce a smaller output because the polyfills will only be bundled once for the entire build instead of per file.
Simply set the target option on the minifier to specify which support level 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 inserted from the 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).
⚠️ esbuild is not stable yet and can have dramatic differences across releases. Using a different version of esbuild is not guaranteed to work.
The implementation option will be removed once esbuild reaches a stable release. Instead esbuild will become a peerDependency so you always provide your own.
Setup examples
If you'd like to see working Webpack builds that use esbuild-loader for basic JS, React, TypeScript, Next.js, etc. check out the examples repo:
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 any JS bundler 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.
The npm package esbuild-loader receives a total of 763,371 weekly downloads. As such, esbuild-loader popularity was classified as popular.
We found that esbuild-loader demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.It has 1 open source maintainer collaborating on the project.
Package last updated on 29 Aug 2023
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
A new Rust RFC proposes "Trusted Publishing" for Crates.io, introducing short-lived access tokens via OIDC to improve security and reduce risks associated with long-lived API tokens.
Cloudflare is expanding Node.js compatibility for Workers and Pages, enabling developers to use more npm packages through a hybrid approach that combines native code and polyfills for Node.js APIs.
The Python Software Foundation has expanded its CNA scope to include the Pallets Projects, enabling faster, more reliable CVE tracking for critical frameworks used in Python applications.