esbuild-config

Config files for esbuild.

Why?

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)

Usage

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)

Syntax

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
}

Output:

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

Install

npm

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.

Binaries

You can download the precompiled binaries from the release page.

Cargo

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 git@github.com:bpierre/esbuild-config.git
cd esbuild-config
cargo build --release

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

Contribute

# Run the app
cargo run

# Run the tests
cargo test

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

FAQ

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

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

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.

License

MIT