Speed up your Webpack build withesbuild!🔥
esbuildis a JavaScript bundler written in Go that supports blazing fast ESNext & TypeScript transpilation andJS minification.
esbuild-loaderlets 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 usingtsx!
tsxis a simple, lightweight, and blazing fast alternative to ts-node.
Already a sponsor?Join the discussion in theDevelopment repo!
npm i -D esbuild-loader
To leverageesbuild-loader
in your Webpack configuration, add a new rule foresbuild-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 yourwebpack.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 theloader
option:
{
test: /\.js$/,
loader: 'esbuild-loader',
options: {
+// Treat `.js` files as `.jsx` files
+loader: 'jsx',
// JavaScript version to transpile to
target: 'es2015'
}
}
esbuild-loader
can be used in-place ofbabel-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 isesnext
,which means it doesn't perform any transpilations.
To specify a target JavaScript engine that only supports ES2015, use the following configuration in yourwebpack.config.js
:
{
test: /\.jsx?$/,
loader: 'esbuild-loader',
options: {
+target: 'es2015',
},
}
For a detailed list of supported transpilations and versions, refer tothe esbuild documentation.
esbuild-loader
can be used in-place ofts-loader
to compile TypeScript.
{
// `.ts` or `.tsx` files
test:/\.tsx?$/,
loader:'esbuild-loader',
}
Important
It's possible to useloader: 'tsx'
for both.ts
and.tsx
files, but this could lead to unexpected behavior as TypeScript and TSX do not have compatible syntaxes.
If you have atsconfig.json
file in your project,esbuild-loader
will automatically load it.
If it's under a custom name, you can pass in the path viatsconfig
option:
{
test: /\.tsx?$/,
loader: 'esbuild-loader',
options: {
+tsconfig: './tsconfig.custom.json',
},
},
Behind the scenes:
get-tsconfig
is used to load the tsconfig, and to also resolve theextends
property if it exists.
ThetsconfigRaw
option can be used to pass in a rawtsconfig
object, but it will not resolve theextends
property.
-
esbuild only supports a subset of
tsconfig
options(seeTransformOptions
interface). -
Enable
isolatedModules
to avoid mis-compilation with features like re-exporting types. -
Enable
esModuleInterop
to make TypeScript's type system compatible with ESM imports. -
Features that require type interpretation, such as
emitDecoratorMetadata
and declaration, are not supported.
→ Read more about TypeScript Caveats
Usetsconfig-paths-webpack-pluginto add support fortsconfig.json#paths
.
Sinceesbuild-loader
only transforms code, it cannot aid Webpack with resolving paths.
esbuilddoes nottype check your code. And according to theesbuild FAQ,it will not be supported.
Consider these type-checking alternatives:
- Using an IDEs likeVSCodeorWebStormthat has live type-checking built in
- Running
tsc --noEmit
to type check - Integrating type-checking to your Webpack build as a separate process using
fork-ts-checker-webpack-plugin
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 theseminification benchmarks.
Inwebpack.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 thetarget
option allows for the use of newer JavaScript syntax, enhancing minification effectiveness.
Webpack'sDefinePlugin
can replaced withEsbuildPlugin
to define global constants. This could speed up the build by removing the parsing costs associated with theDefinePlugin
.
Inwebpack.config.js
:
-const { DefinePlugin } = require('webpack')
+const { EsbuildPlugin } = require('esbuild-loader')
module.exports = {
//...,
plugins:[
-new DefinePlugin({
-'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
-})
+new EsbuildPlugin({
+define: {
+'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
+},
+}),
]
}
If your project does not use TypeScript, JSX, or any other syntax that requires additional configuration beyond what Webpack provides, you can useEsbuildPlugin
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 thetarget
option on the plugin to specify which syntax support you want.
Depending on your setup, there are two ways to minify CSS. You should already have CSS loading setup usingcss-loader
.
If the CSS is extracted and emitted as.css
file, you can replace CSS minification plugins likecss-minimizer-webpack-plugin
with theEsbuildPlugin
.
Assuming the CSS is extracted using something likeMiniCssExtractPlugin,inwebpack.config.js
:
const { EsbuildPlugin } = require('esbuild-loader')
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
module.exports = {
//...,
optimization: {
minimizer: [
new EsbuildPlugin({
target: 'es2015',
+css: true // Apply minification to CSS assets
})
]
},
module: {
rules: [
{
test: /\.css$/i,
use: [
MiniCssExtractPlugin.loader,
'css-loader'
]
}
],
},
plugins: [
new MiniCssExtractPlugin()
]
}
If your CSS is not emitted as a.css
file, but rather injected with JavaScript using something likestyle-loader
,you can use the loader for minification.
Inwebpack.config.js
:
module.exports = {
//...,
module: {
rules: [
{
test: /\.css$/i,
use: [
'style-loader',
'css-loader',
+{
+loader: 'esbuild-loader',
+options: {
+minify: true,
+},
+},
],
},
],
},
}
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 theimplementation
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.
+const esbuild = require('esbuild')
module.exports = {
//...,
module: {
rules: [
{
test:...,
loader: 'esbuild-loader',
options: {
//...,
+implementation: esbuild,
},
},
],
},
}
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 loader supportsall Transform options from esbuild.
Note:
- Source-maps are automatically configured for you via
devtool
.sourcemap
/sourcefile
options are ignored. - The root
tsconfig.json
is automatically detected for you. You don't need to pass intsconfigRaw
unless it's in a different path.
Here are some common configurations and custom options:
Type:string
Pass in the file path to acustomtsconfig file. If the file name istsconfig.json
,it will automatically detect it.
Type:string | Array<string>
Default:'es2015'
The target environment (e.g.es2016
,chrome80
,esnext
).
Read more about it in theesbuild docs.
Type:'js' | 'jsx' | 'ts' | 'tsx' | 'css' | 'json' | 'text' | 'base64' | 'file' | 'dataurl' | 'binary' | 'default'
Default:'default'
The loader to use to handle the file. See the type forpossible values.
By default, it automatically detects the loader based on the file extension.
Read more about it in theesbuild docs.
Type:string
Default:React.createElement
Customize the JSX factory function name to use.
Read more about it in theesbuild docs.
Type:string
Default:React.Fragment
Customize the JSX fragment function name to use.
Read more about it in theesbuild docs.
Type:{ transform: Function }
Custom esbuild-loader option.
Use it to pass in adifferent esbuild version.
The loader supportsall Transform options from esbuild.
Type:string | Array<string>
Default:'esnext'
Target environment (e.g.'es2016'
,['chrome80', 'esnext']
)
Read more about it in theesbuild docs.
Here are some common configurations and custom options:
Type:'iife' | 'cjs' | 'esm'
Default:
iife
if both of these conditions are met:undefined
(no format conversion) otherwise
The default isiife
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 settingformat: 'iife'
,esbuild wraps the helper functions in anIIFEto prevent them from polluting the global.
Read more about it in theesbuild docs.
Type:boolean
Default:true
Enable JS minification. Enables allminify*
flags below.
To have nuanced control over minification, disable this and enable the specific minification you want below.
Read more about it in theesbuild docs.
Type:boolean
Minify JS by removing whitespace.
Type:boolean
Minify JS by shortening identifiers.
Type:boolean
Minify JS using equivalent but shorter syntax.
Type:'none' | 'inline' | 'eof' | 'external'
Default:'inline'
Read more about it in theesbuild docs.
Type:boolean
Default:false
Whether to minify CSS files.
Type:string | RegExp | Array<string | RegExp>
To only apply the plugin to certain assets, pass in filters include
Type:string | RegExp | Array<string | RegExp>
To prevent the plugin from applying to certain assets, pass in filters to exclude
Type:{ transform: Function }
Use it to pass in adifferent esbuild version.
For personalized assistance, take advantage of myPriority Supportservice.
Whether it's about Webpack configuration, esbuild, or TypeScript, I'm here to guide you every step of the way!
No. esbuild plugins areonly 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 usingesbuild-loader
to transpile just the JS part of the SFC.
Is it possible to use esbuild'sinjectoption?
No. Theinject
option is only available in the build API. And esbuild-loader uses the transform API.
However, you can use the Webpack equivalentProvidePlugininstead.
If you're using React, check outthis exampleon how to auto-import React in your components.
No. If you really need them, consider porting them over to a Webpack loader.
And please don't chainbabel-loader
andesbuild-loader
.The speed gains come from replacingbabel-loader
.
Why am I not getting a100x speed improvementas advertised?
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 ithere.
- 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 bybabel-loader
,ts-loader
,Terser, etc.
Node.js enhanced with esbuild to run TypeScript and ESM.
Webpack-integrated Mocha test-runner with Webpack 5 support.
Localize/i18nalize your Webpack build. Optimized for multiple locales!