Esbuild

Mix tasks for installing and invoking esbuild.

Installation

If you are going to build assets in production, then you add esbuild as dependency on all environments but only start it in dev:

def deps do
  [
    {:esbuild, "~> 0.1", runtime: Mix.env() == :dev}
  ]
end

However, if your assets are precompiled during development, then it only needs to be a dev dependency:

def deps do
  [
    {:esbuild, "~> 0.1", only: :dev}
  ]
end

Once installed, change your config/config.exs to pick your esbuild version of choice:

config :esbuild, version: "0.12.17"

Now you can install esbuild by running:

$ mix esbuild.install

And invoke esbuild with:

$ mix esbuild default assets/js/app.js --bundle --minify --target=es2016 --outdir=priv/static/assets/

The executable is kept at _build/esbuild.

Profiles

The first argument to esbuild is the execution profile. You can define multiple execution profiles with the current directory, the OS enviroment, and default arguments to the esbuild task:

config :esbuild,
  version: "0.12.17",
  default: [
    args: ~w(js/app.js),
    cd: Path.expand("../assets", __DIR__)
  ]

When mix esbuild default is invoked, the task arguments will be appended to the ones configured above.

Adding to Phoenix

To add esbuild to an application using Phoenix, you need only four steps.

First add it as a dependency in your mix.exs:

def deps do
  [
    {:esbuild, "~> 0.1", runtime: Mix.env() == :dev}
  ]
end

Now let's configure esbuild to use assets/js/app.js as an entry point and write to priv/static/assets:

config :esbuild,
  version: "0.12.17",
  default: [
    args: ~w(js/app.js --bundle --target=es2016 --outdir=../priv/static/assets),
    cd: Path.expand("../assets", __DIR__),
    env: %{"NODE_PATH" => Path.expand("../deps", __DIR__)}
  ]

Make sure the "assets" directory from priv/static is listed in the :only option for Plug.Static in your lib/my_app_web/endpoint.ex

For development, we want to enable watch mode. So find the watchers configuration in your config/dev.exs and add:

  esbuild: {Esbuild, :install_and_run, [:default, ~w(--sourcemap=inline --watch)]}

Note we are inlining source maps and enabling the file system watcher.

Finally, back in your mix.exs, make sure you have a assets.deploy alias for deployments, which will also use the --minify option:

"assets.deploy": ["esbuild default --minify", "phx.digest"]

License

esbuild source code is licensed under the MIT License.