Socket
Socket
Sign inDemoInstall

esbuild-loader

Package Overview
Dependencies
107
Maintainers
1
Versions
49
Alerts
File Explorer

Advanced tools

npm Scripts

Install Socket

Detect and block malicious and high-risk dependencies

Install

Comparing version 3.0.1 to 3.1.0

6

package.json
{
"name": "esbuild-loader",
"version": "3.0.1",
"version": "3.1.0",
"description": "⚡️ Speed up your Webpack build with esbuild",

@@ -43,4 +43,4 @@ "keywords": [

"dependencies": {
"esbuild": "^0.17.6",
"get-tsconfig": "^4.4.0",
"esbuild": "^0.18.17",
"get-tsconfig": "^4.6.2",
"loader-utils": "^2.0.4",

@@ -47,0 +47,0 @@ "webpack-sources": "^1.4.3"

368

README.md

@@ -7,3 +7,3 @@ # esbuild-loader <a href="https://npm.im/esbuild-loader"><img src="https://badgen.net/npm/v/esbuild-loader"></a> <a href="https://npm.im/esbuild-loader"><img src="https://badgen.net/npm/dm/esbuild-loader"></a> <a href="https://packagephobia.now.sh/result?p=esbuild-loader"><img src="https://packagephobia.now.sh/badge?p=esbuild-loader"></a>

[_esbuild-loader_](https://github.com/esbuild-kit/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)!
[_esbuild-loader_](https://github.com/esbuild-kit/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)!

@@ -13,11 +13,8 @@ Curious how much faster your build will be? See [what users are saying](https://github.com/esbuild-kit/esbuild-loader/discussions/138).

---
> **🤫 Psst! Want to power up your Node.js with esbuild?**
> **💡 Protip: Enhance your Node.js DX with `tsx`**
>
> Checkout our new project [`tsx`](https://github.com/esbuild-kit/tsx), an esbuild enhanced Node.js runtime that can run TypeScript instantly!
> If you're interested in supercharging your Node.js runtime with esbuild, take a look at our new project [`tsx`](https://github.com/esbuild-kit/tsx). It's an esbuild-enhanced Node.js runtime that can run TypeScript instantly!
---
<sub>Support this project by ⭐️ starring and sharing it. [Follow me](https://github.com/privatenumber) to see what other cool projects I'm working on! ❤️</sub>
<sub>Found this package useful? Show your support & appreciation by [sponsoring](https://github.com/sponsors/privatenumber)! ❤️</sub>

@@ -32,65 +29,149 @@ ## 🚀 Install

Use `esbuild-loader` to transform new JavaScript syntax to support older browsers, and TypeScript to JavaScript
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`).
In your Webpack configuration, add a new rule for `esbuild-loader` matching the files you want to transform (e.g. `.js`, `.jsx`, `.ts`, `.tsx`).
Here's an example of how to set it up in your `webpack.config.js`:
If you were using other loaders before (e.g. `babel-loader`/`ts-loader`), make sure to remove them.
`webpack.config.js`:
```diff
module.exports = {
module: {
rules: [
- {
- test: /\.js$/,
- use: 'babel-loader'
- },
- {
- test: /\.tsx?$/,
- use: 'ts-loader'
- },
+ {
+ // Match js, jsx, ts & tsx files
+ test: /\.[jt]sx?$/,
+ loader: 'esbuild-loader',
+ options: {
+ // JavaScript version to compile to
+ target: 'es2015'
+ }
+ },
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`](https://github.com/esbuild-kit/esbuild-loader/#loader) option:
```diff
{
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`:
```diff
{
test: /\.jsx?$/,
loader: 'esbuild-loader',
options: {
+ target: 'es2015',
},
}
```
For a detailed list of supported transpilations and versions, refer to [the esbuild documentation](https://esbuild.github.io/content-types/#javascript).
### TypeScript
`esbuild-loader` can be used in-place of `ts-loader` to compile TypeScript.
```json5
{
// `.ts` or `.tsx` files
test: /\.tsx?$/,
loader: 'esbuild-loader',
}
```
> Note: You cannot use the `tsx` loader for `*.ts` files as it has incompatible syntax with the `ts` loader.
>
> [→ Read more](https://esbuild.github.io/content-types/#ts-vs-tsx)
#### `tsconfig.json`
If you have a `tsconfig.json` file in your project, esbuild-loader will automatically load it.
If you have a `tsconfig.json` file in your project, `esbuild-loader` will automatically load it.
If you use a custom name, you can pass it in the path via `tsconfig` option:
If it's under a custom name, you can pass in the path via `tsconfig` option:
```diff
{
{
test: /\.tsx?$/,
loader: 'esbuild-loader',
options: {
+ tsconfig: './tsconfig.custom.json'
}
}
+ tsconfig: './tsconfig.custom.json',
},
},
```
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.
> 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.
You can also use the `tsconfigRaw` option to pass in a raw `tsconfig` object, but it will not resolve the `extends` property.
⚠️ esbuild only supports a subset of `tsconfig` options [(see `TransformOptions` interface)](https://github.com/evanw/esbuild/blob/88821b7e7d46737f633120f91c65f662eace0bcf/lib/shared/types.ts#L159-L165) 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`](https://www.typescriptlang.org/tsconfig#isolatedModules) and [`esModuleInterop`](https://www.typescriptlang.org/tsconfig/#esModuleInterop) options in your `tsconfig` by the [esbuild docs](https://esbuild.github.io/content-types/#typescript-caveats).
##### Caveats
- esbuild only supports a subset of `tsconfig` options [(see `TransformOptions` interface)](https://github.com/evanw/esbuild/blob/88821b7e7d46737f633120f91c65f662eace0bcf/lib/shared/types.ts#L159-L165).
- Enable [`isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules) to avoid mis-compilation with features like re-exporting types.
- Enable [`esModuleInterop`](https://www.typescriptlang.org/tsconfig/#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](https://esbuild.github.io/content-types/#typescript-caveats)
#### `tsconfig.json` Paths
Use [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).
Since esbuild-loader only uses esbuild to transform code, it cannot help Webpack with resolving paths.
Since `esbuild-loader` only transforms code, it cannot aid Webpack with resolving paths.
#### Type-checking
esbuild **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.
Consider these type-checking alternatives:
- 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
- Running `tsc --noEmit` to type check
- 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)
## EsbuildPlugin
### Minification

@@ -105,25 +186,59 @@ You can replace JS minifiers like Terser or UglifyJs. Checkout the [benchmarks](https://github.com/privatenumber/minification-benchmarks) to see how much faster esbuild is. The `target` option tells esbuild that it can use newer JS syntax to perform better minification.

module.exports = {
...,
...,
+ optimization: {
+ minimizer: [
+ new EsbuildPlugin({
+ target: 'es2015' // Syntax to compile to (see options below for possible values)
+ })
+ ]
+ },
+ optimization: {
+ minimizer: [
+ new EsbuildPlugin({
+ target: 'es2015' // Syntax to transpile to (see options below for possible values)
+ })
+ ]
+ },
}
```
#### _💁‍♀️ Protip: Use the 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.
### Defining constants
You can replace the [`DefinePlugin`](https://webpack.js.org/plugins/define-plugin/) to define global constants. The parsing cost of the DefinePlugin is often overlooked so replacing it with esbuild can speed up the build.
### CSS Minification
In `webpack.config.js`:
There are two ways to minify CSS, depending on your setup. You should already have CSS setup in your build using [`css-loader`](https://github.com/webpack-contrib/css-loader).
```diff
- const { DefinePlugin } = require('webpack')
+ const { EsbuildPlugin } = require('esbuild-loader')
#### CSS assets
If the CSS is extracted and emitted as a separate file, you can replace CSS minification plugins like [`css-minimizer-webpack-plugin`](https://github.com/webpack-contrib/css-minimizer-webpack-plugin) with the `EsbuildPlugin`.
module.exports = {
// ...,
plugins:[
- new DefinePlugin({
- 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
- })
+ new EsbuildPlugin({
+ options: {
+ define: {
+ 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
+ },
+ },
+ }),
]
}
```
### Transpilation
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`](https://github.com/webpack-contrib/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`](https://github.com/webpack-contrib/css-minimizer-webpack-plugin) with the `EsbuildPlugin`.
Assuming the CSS is extracted using something like [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin), in `webpack.config.js`:

@@ -136,28 +251,28 @@

module.exports = {
...,
// ...,
optimization: {
minimizer: [
new EsbuildPlugin({
target: 'es2015',
+ css: true // Apply minification to CSS assets
})
]
},
optimization: {
minimizer: [
new EsbuildPlugin({
target: 'es2015',
+ css: true // Apply minification to CSS assets
})
]
},
module: {
rules: [
{
test: /\.css$/i,
use: [
MiniCssExtractPlugin.loader,
'css-loader'
]
}
module: {
rules: [
{
test: /\.css$/i,
use: [
MiniCssExtractPlugin.loader,
'css-loader'
]
}
],
},
plugins: [
new MiniCssExtractPlugin()
]
},
plugins: [
new MiniCssExtractPlugin()
]
}

@@ -167,5 +282,5 @@ ```

#### CSS in JS
### CSS in JS
If your CSS is not emitted as a CSS file, but rather loaded via JS using something like [`style-loader`](https://github.com/webpack-contrib/style-loader), you can use the loader for minification.
If your CSS is not emitted as a `.css` file, but rather inserted from the JavaScript using something like [`style-loader`](https://github.com/webpack-contrib/style-loader), you can use the loader for minification.

@@ -177,29 +292,26 @@

module.exports = {
...,
// ...,
module: {
rules: [
{
test: /\.css$/i,
use: [
'style-loader',
'css-loader',
+ {
+ loader: 'esbuild-loader',
+ options: {
+ minify: true
+ }
+ }
]
}
]
}
module: {
rules: [
{
test: /\.css$/i,
use: [
'style-loader',
'css-loader',
+ {
+ loader: 'esbuild-loader',
+ options: {
+ 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](https://github.com/esbuild-kit/esbuild-loader-examples).
## Bring your own esbuild (Advanced)
### Bring your own esbuild (Advanced)
esbuild-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.

@@ -215,19 +327,17 @@

...
module.exports = {
...,
// ...,
module: {
rules: [
{
test: ...,
loader: 'esbuild-loader',
options: {
...,
+ implementation: esbuild
}
}
]
}
module: {
rules: [
{
test: ...,
loader: 'esbuild-loader',
options: {
// ...,
+ implementation: esbuild,
},
},
],
},
}

@@ -239,2 +349,7 @@ ```

## 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:
[→ esbuild-loader examples](https://github.com/esbuild-kit/esbuild-loader-examples)
## ⚙️ Options

@@ -415,10 +530,3 @@

### Will there be type-checking support?
According to the [esbuild FAQ](https://esbuild.github.io/faq/#:~:text=typescript%20type%20checking%20(just%20run%20tsc%20separately)), it will not be supported.
Consider these type-checking alternatives:
- 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
- Running `tsc --noEmit` to type check
- 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)
## 💞 Related

@@ -434,1 +542,9 @@

Localize/i18nalize your Webpack build. Optimized for multiple locales!
## Sponsors
<p align="center">
<a href="https://github.com/sponsors/privatenumber">
<img src="https://cdn.jsdelivr.net/gh/privatenumber/sponsors/sponsorkit/sponsors.svg">
</a>
</p>
dist/index.cjs

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

About

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc