![](\".github/logo.svg\"){kind=logo}
\n \n esbuild-loader\n
\n
\n \n\t![](\"https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/donate.webp\")
\n\t![](\"https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/sponsor.webp\")
\n
Already a sponsor? Join the discussion in the Development repo!
\n\n## 🚀 Install\n\n```bash\nnpm i -D esbuild-loader\n```\n\n## 🚦 Quick Setup\n\nTo 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`).\n\nHere's an example of how to set it up in your `webpack.config.js`:\n\n```diff\n module.exports = {\n module: {\n rules: [\n- // Transpile JavaScript\n- {\n- test: /\\.js$/,\n- use: 'babel-loader'\n- },\n-\n- // Compile TypeScript\n- {\n- test: /\\.tsx?$/,\n- use: 'ts-loader'\n- },\n+ // Use esbuild to compile JavaScript & TypeScript\n+ {\n+ // Match `.js`, `.jsx`, `.ts` or `.tsx` files\n+ test: /\\.[jt]sx?$/,\n+ loader: 'esbuild-loader',\n+ options: {\n+ // JavaScript version to compile to\n+ target: 'es2015'\n+ }\n+ },\n\n // Other rules...\n ],\n },\n }\n```\n\nIn this setup, esbuild will automatically determine how to handle each file based on its extension:\n- `.js` files will be treated as JS (no JSX allowed)\n- `.jsx` as JSX\n- `.ts` as TS (no TSX allowed)\n- `.tsx` as TSX\n\n\nIf 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](https://github.com/privatenumber/esbuild-loader/#loader):\n\n```diff\n {\n test: /\\.js$/,\n loader: 'esbuild-loader',\n options: {\n+ // Treat `.js` files as `.jsx` files\n+ loader: 'jsx',\n\n // JavaScript version to transpile to\n target: 'es2015'\n }\n }\n```\n\n\n## Loader\n\n### JavaScript\n\n`esbuild-loader` can be used in-place of `babel-loader` to transpile new JavaScript syntax into code compatible with older JavaScript engines.\n\nWhile this ensures your code can run smoothly across various environments, note that it can bloat your output code (like Babel).\n\nThe default target is `esnext`, which means it doesn't perform any transpilations.\n\nTo specify a target JavaScript engine that only supports ES2015, use the following configuration in your `webpack.config.js`:\n\n```diff\n {\n test: /\\.jsx?$/,\n loader: 'esbuild-loader',\n options: {\n+ target: 'es2015',\n },\n }\n```\n\nFor a detailed list of supported transpilations and versions, refer to [the esbuild documentation](https://esbuild.github.io/content-types/#javascript).\n\n### TypeScript\n\n`esbuild-loader` can be used in-place of `ts-loader` to compile TypeScript.\n\n```js\n({\n // `.ts` or `.tsx` files\n test: /\\.tsx?$/,\n loader: 'esbuild-loader'\n})\n```\n\n\n> [!IMPORTANT]\n> 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.\n>\n> [→ Read more](https://esbuild.github.io/content-types/#ts-vs-tsx)\n\n#### `tsconfig.json`\nIf you have a `tsconfig.json` file in your project, `esbuild-loader` will automatically load it.\n\nIf it's under a custom name, you can pass in the path via `tsconfig` option:\n```diff\n {\n test: /\\.tsx?$/,\n loader: 'esbuild-loader',\n options: {\n+ tsconfig: './tsconfig.custom.json',\n },\n },\n```\n\n> Behind the scenes: [`get-tsconfig`](https://github.com/privatenumber/get-tsconfig) is used to load the tsconfig, and to also resolve the `extends` property if it exists.\n\nThe `tsconfigRaw` option can be used to pass in a raw `tsconfig` object, but it will not resolve the `extends` property.\n\n\n##### Caveats\n- esbuild only supports a subset of `tsconfig` options [(see `TransformOptions` interface)](https://github.com/evanw/esbuild/blob/88821b7e7d46737f633120f91c65f662eace0bcf/lib/shared/types.ts#L159-L165).\n\n- Enable [`isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules) to avoid mis-compilation with features like re-exporting types.\n\n- Enable [`esModuleInterop`](https://www.typescriptlang.org/tsconfig/#esModuleInterop) to make TypeScript's type system compatible with ESM imports.\n\n- Features that require type interpretation, such as `emitDecoratorMetadata` and declaration, are not supported.\n\n[→ Read more about TypeScript Caveats](https://esbuild.github.io/content-types/#typescript-caveats)\n\n#### `tsconfig.json` Paths\nUse [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin) to add support for [`tsconfig.json#paths`](https://www.typescriptlang.org/tsconfig/paths.html).\n\nSince `esbuild-loader` only transforms code, it cannot aid Webpack with resolving paths.\n\n\n#### Type-checking\n\nesbuild **does not** type check your code. And according to the [esbuild FAQ](https://esbuild.github.io/faq/#:~:text=typescript%20type%20checking%20(just%20run%20tsc%20separately)), it will not be supported.\n\nConsider these type-checking alternatives:\n- Using an IDEs like [VSCode](https://code.visualstudio.com/docs/languages/typescript) or [WebStorm](https://www.jetbrains.com/help/webstorm/typescript-support.html) that has live type-checking built in\n- Running `tsc --noEmit` to type check\n- Integrating type-checking to your Webpack build as a separate process using [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin)\n\n### Defining constants\n\nUse the [`define`](#define) option to replace global identifiers with constant expressions:\n\n```diff\n {\n test: /\\.[jt]sx?$/,\n loader: 'esbuild-loader',\n options: {\n+ define: {\n+ 'process.env.NODE_ENV': JSON.stringify('production'),\n+ },\n },\n }\n```\n\n> [!TIP]\n> The loader's `define` works with **all devtools**, including eval-based ones. If you're using the [plugin's `define`](#defining-constants-1) and it's not working, try the loader instead.\n\n## EsbuildPlugin\n\n### Minification\nEsbuild 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](https://github.com/privatenumber/minification-benchmarks).\n\nIn `webpack.config.js`:\n\n```diff\n+ const { EsbuildPlugin } = require('esbuild-loader')\n\n module.exports = {\n ...,\n\n+ optimization: {\n+ minimizer: [\n+ new EsbuildPlugin({\n+ target: 'es2015' // Syntax to transpile to (see options below for possible values)\n+ })\n+ ]\n+ },\n }\n```\n\n> [!TIP]\n> Utilizing the `target` option allows for the use of newer JavaScript syntax, enhancing minification effectiveness.\n\n### Defining constants\n\nWebpack's [`DefinePlugin`](https://webpack.js.org/plugins/define-plugin/) can replaced with `EsbuildPlugin` to define global constants. This could speed up the build by removing the parsing costs associated with the `DefinePlugin`.\n\nIn `webpack.config.js`:\n\n```diff\n- const { DefinePlugin } = require('webpack')\n+ const { EsbuildPlugin } = require('esbuild-loader')\n\n module.exports = {\n // ...,\n\n plugins:[\n- new DefinePlugin({\n- 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),\n- })\n+ new EsbuildPlugin({\n+ define: {\n+ 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),\n+ },\n+ }),\n ]\n }\n```\n\n> [!WARNING]\n> 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](#define) instead, which transforms files before bundling.\n\n### Transpilation\n\nIf 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.\n\nIt 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.\n\nTo utilize esbuild for transpilation, simply set the `target` option on the plugin to specify which syntax support you want.\n\n\n## CSS Minification\n\nDepending on your setup, there are two ways to minify CSS. You should already have CSS loading setup using [`css-loader`](https://github.com/webpack-contrib/css-loader).\n\n### CSS assets\nIf the CSS is extracted and emitted as `.css` file, you can replace CSS minification plugins like [`css-minimizer-webpack-plugin`](https://github.com/webpack-contrib/css-minimizer-webpack-plugin) with the `EsbuildPlugin`.\n\nAssuming the CSS is extracted using something like [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin), in `webpack.config.js`:\n\n```diff\n const { EsbuildPlugin } = require('esbuild-loader')\n const MiniCssExtractPlugin = require('mini-css-extract-plugin');\n\n module.exports = {\n // ...,\n\n optimization: {\n minimizer: [\n new EsbuildPlugin({\n target: 'es2015',\n+ css: true // Apply minification to CSS assets\n })\n ]\n },\n\n module: {\n rules: [\n {\n test: /\\.css$/i,\n use: [\n MiniCssExtractPlugin.loader,\n 'css-loader'\n ]\n }\n ],\n },\n\n plugins: [\n new MiniCssExtractPlugin()\n ]\n }\n```\n\n\n### CSS in JS\n\nIf your CSS is not emitted as a `.css` file, but rather injected with JavaScript using something like [`style-loader`](https://github.com/webpack-contrib/style-loader), you can use the loader for minification.\n\n\nIn `webpack.config.js`:\n\n```diff\n module.exports = {\n // ...,\n\n module: {\n rules: [\n {\n test: /\\.css$/i,\n use: [\n 'style-loader',\n 'css-loader',\n+ {\n+ loader: 'esbuild-loader',\n+ options: {\n+ minify: true,\n+ },\n+ },\n ],\n },\n ],\n },\n }\n```\n\n## Bring your own esbuild (Advanced)\n\nesbuild-loader comes with a version of esbuild it has been tested to work with. However, [esbuild has a frequent release cadence](https://github.com/evanw/esbuild/releases), and while we try to keep up with the important releases, it can get outdated.\n\nTo 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).\n\n> [!WARNING] \n> ⚠esbuild is not stable yet and can have dramatic differences across releases. Using a different version of esbuild is not guaranteed to work.\n\n\n```diff\n+ const esbuild = require('esbuild')\n\n module.exports = {\n // ...,\n\n module: {\n rules: [\n {\n test: ...,\n loader: 'esbuild-loader',\n options: {\n // ...,\n+ implementation: esbuild,\n },\n },\n ],\n },\n }\n```\n\n## Setup examples\nIf 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:\n\n[→ esbuild-loader examples](https://github.com/privatenumber/esbuild-loader-examples)\n\n## ⚙️ Options\n\n### Loader\nThe loader supports [all Transform options from esbuild](https://github.com/evanw/esbuild/blob/88821b7e7d46737f633120f91c65f662eace0bcf/lib/shared/types.ts#L158-L172).\n\nNote:\n- Source-maps are automatically configured for you via [`devtool`](https://webpack.js.org/configuration/devtool/). `sourcemap`/`sourcefile` options are ignored.\n- The root `tsconfig.json` is automatically detected for you. You don't need to pass in [`tsconfigRaw`](https://esbuild.github.io/api/#tsconfig-raw) unless it's in a different path.\n\n\nHere are some common configurations and custom options:\n\n#### tsconfig\n\nType: `string`\n\nPass in the file path to a **custom** tsconfig file. If the file name is `tsconfig.json`, it will automatically detect it.\n\n#### target\nType: `string | Array\n\t\n\t\t![](\"https://cdn.jsdelivr.net/gh/privatenumber/sponsors/sponsorkit/sponsors.svg\")
\n\t\n