esbuild-loader

What is esbuild-loader?

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.

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'esbuild-loader',
            options: {
              loader: 'css',
              minify: true
            }
          }
        ]
      }
    ]
  }
};

Other packages similar to esbuild-loader

babel-loader

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

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

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.

README

esbuild-loader

Speed up your Webpack build with esbuild! 🔥

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)!

Curious how much faster your build will be? See what users are saying.

_{If you like this project, please star it & follow me to see what other cool projects I'm working on! ❤️}

🚀 Install

npm i -D esbuild-loader

🚦 Quick Setup

Javascript & JSX transpilation (eg. Babel)

In webpack.config.js:

  module.exports = {
    module: {
      rules: [
-       {
-         test: /\.js$/,
-         use: 'babel-loader',
-       },
+       {
+         test: /\.js$/,
+         loader: 'esbuild-loader',
+         options: {
+           loader: 'jsx',  // Remove this if you're not using JSX
+           target: 'es2015'  // Syntax to compile to (see options below for possible values)
+         }
+       },

        ...
      ],
    },
  }

TypeScript & TSX

In webpack.config.js:

  module.exports = {
    module: {
      rules: [
-       {
-         test: /\.tsx?$/,
-         use: 'ts-loader'
-       },
+       {
+         test: /\.tsx?$/,
+         loader: 'esbuild-loader',
+         options: {
+           loader: 'tsx',  // Or 'ts' if you don't need tsx
+           target: 'es2015'
+         }
+       },

        ...
      ]
    },
  }

Configuration

If you have a tsconfig.json file, esbuild-loader will automatically detect it.

Alternatively, you can also pass it in directly via the tsconfigRaw option:

  {
      test: /\.tsx?$/,
      loader: 'esbuild-loader',
      options: {
          loader: 'tsx',
          target: 'es2015',
+         tsconfigRaw: require('./tsconfig.json')
      }
  }

⚠️ esbuild only supports a subset of tsconfig options (see TransformOptions interface) and does not do type-checks. It's recommended to use a type-aware IDE or tsc --noEmit for type-checking instead. It is also recommended to enable isolatedModules and esModuleInterop options in your tsconfig by the esbuild docs.

JS Minification (eg. Terser)

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 { ESBuildMinifyPlugin } = require('esbuild-loader')

  module.exports = {
    ...,

+   optimization: {
+     minimizer: [
+       new ESBuildMinifyPlugin({
+         target: 'es2015'  // Syntax to compile to (see options below for possible values)
+       })
+     ]
+   },
  }

💁‍♀️ Protip: Use the minify plugin in-place of the loader to transpile the JS

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

There are two ways to minify CSS, depending on your setup. You should already have CSS setup in your build using css-loader.

⚠️ esbuild currently doesn't support source-maps for CSS minification.

CSS assets

If your CSS is extracted and emitted as a CSS file, you can replace CSS minification plugins like css-minimizer-webpack-plugin or optimize-css-assets-webpack-plugin with the same ESBuildMinifyPlugin by enabling the css option.

Assuming the CSS is extracted using something like MiniCssExtractPlugin, in webpack.config.js:

  const { ESBuildMinifyPlugin } = require('esbuild-loader')
  const MiniCssExtractPlugin = require('mini-css-extract-plugin');

  module.exports = {
    ...,

    optimization: {
      minimizer: [
        new ESBuildMinifyPlugin({
          target: 'es2015',
+         css: true  // Apply minification to CSS assets
        })
      ]
    },

    module: {
      rules: [
        {
          test: /\.css$/i,
          use: [
            MiniCssExtractPlugin.loader,
            'css-loader'
          ]
        }
      ]
    },

    plugins: [
      new MiniCssExtractPlugin()
    ]
  }

CSS in JS

If your CSS is not emitted as a CSS file, but rather loaded via JS using something like style-loader, you can use the loader for minification.

In webpack.config.js:

  module.exports = {
    ...,

    module: {
      rules: [
        {
          test: /\.css$/i,
          use: [
            'style-loader',
            'css-loader',
+           {
+             loader: 'esbuild-loader',
+             options: {
+               loader: 'css',
+               minify: true
+             }
+           }
          ]
        }
      ]
    }
  }

Examples

If you'd like to see working Webpack builds that use esbuild-loader for basic JS, React, TypeScript, or Next.js, check out the examples repo.

⚙️ Options

Loader

The loader supports options from esbuild.

• target String ('es2015') - Environment target (e.g. es2016, chrome80, esnext)
• loader String ('js') - Which loader to use to handle file
  • Possible values: js, jsx, ts, tsx, json, text, base64, file, dataurl, binary
• jsxFactory String - What to use instead of React.createElement
• jsxFragment String - What to use instead of React.Fragment

Enable source-maps via devtool

MinifyPlugin

• target String|Aray<String> ('esnext') - Environment target (e.g. 'es2016', ['chrome80', 'esnext'])
• minify Boolean (true) - Sets all minify flags
• minifyWhitespace Boolean - Remove whitespace
• minifyIdentifiers Boolean - Shorten identifiers
• minifySyntax Boolean - Use equivalent but shorter syntax
• sourcemap Boolean (defaults to Webpack devtool) - Whether to emit sourcemaps
• css Boolean (false) - Whether to minify CSS files
• include String|RegExp|Array<String|RegExp> - Filter assets for inclusion in minification
• exclude String|RegExp|Array<String|RegExp> - Filter assets for exclusion in minification

💼 License

• MIT © privatenumber
• MIT © EGOIST (Kevin Titor)