Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Config files for esbuild.


esbuild is an incredible tool, that is using command line parameters as a configuration syntax. This is fine, but some people might prefer using a configuration file.

esbuild-config can transform a esbuild.config.json configuration file like this one:

  "entry": "./index.js",
  "outfile": "./bundle.js",
  "external": ["react", "react-dom"],
  "loader": { ".js": "jsx", ".png": "base64" },
  "minify": true

Into a set of parameters for esbuild:

--outfile=./bundle.js --minify --external:react --external:react-dom --loader:.js=jsx --loader:.png=base64 ./index.js

Which means that esbuild can read a static configuration by running it this way:

esbuild $(esbuild-config)


The esbuild-config command outputs a list of parameters based on a esbuild.config.json file, that can get passed to esbuild directly:

esbuild $(esbuild-config)

It detects the presence of esbuild.config.json in the current directory or the project root (using the presence of a package.json file). The same configuration format can also get defined in the package.json file, using the esbuild field.json` file.

A specific file path can also get passed as a parameter:

esbuild $(esbuild-config ./my-conf.json)


esbuild-config doesnโ€™t do any validation on the configuration values: it only converts JSON types into arguments that are compatible with the format esbuild uses for its arguments. This makes it independent from esbuild versions, assuming the format doesnโ€™t change.

The only exception to this is the entry field, which gets converted into a list of file names (when an array is provided) or a single file name (when a string is provided).

This is how JSON types get converted:

  "entry": "./index.js",
  "outfile": "./bundle.js",
  "external": ["react", "react-dom"],
  "loader": { ".js": "jsx", ".png": "base64" },
  "minify": true


--outfile=./bundle.js --minify --external:react --external:react-dom --loader:.js=jsx --loader:.png=base64 ./index.js

Notice how the entry, ./index.js, has been moved to the end. esbuild-config also takes care of escaping the parameters as needed (e.g. by adding quotes).



The easiest way to install esbuild-config is through npm.

Install it globally using the following command:

npm install --global esbuild-config

Or add it to your project:

npm install --save-dev esbuild-config

See below for alternative installation methods.


You can download the precompiled binaries from the release page.


Install it with Cargo using the following command:

cargo install esbuild-config

From source

To clone the repository and build esbuild-config, run these commands (after having installed Rust):

git clone
cd esbuild-config
cargo build --release

The compiled binary is at target/release/esbuild-config.


# Run the app
cargo run

# Run the tests
cargo test

# Generate the code coverage report (install cargo-tarpaulin first)
cargo tarpaulin -o Html


Doesnโ€™t esbuild already support config files?

The recommended way to use a configuration file with esbuild is through its Node.js API, using a Node program as a configuration file:

const { build } = require('esbuild')

  entryPoints: ['./index.js'],
  outfile: './bundle.js',
  external: ['react', 'react-dom'],
  loader: { '.js': 'jsx', '.png': 'base64' },
  minify: true,
}).catch((error) => {

If it works for you, you donโ€™t need esbuild-config: the esbuild module already comes bundled with this JS API. esbuild-config provides an alternative way to configure esbuild. Instead of using the esbuild API through Node.js, it converts a configuration file into command line parameters, that can be passed directly to the esbuild binary.

There are several reasons why you might want to use esbuild-config:

  • You prefer using JSON as a configuration language.
  • You prefer to have as much configuration as possible in the package.json.
  • You prefer to not launch Node at all in the process.

Special thanks

esbuild and its author obviously, not only for esbuild itself but also for its approach to install a platform-specific binary through npm, that esbuild-config is also using.