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.7", 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.7", only: :dev}
  ]
end

Once installed, change your config/config.exs and pick a version
for the esbuild CLI of your choice:

config :esbuild, version: "0.18.6"

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-TARGET.
Where TARGET is your system target architecture.

Profiles

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

config :esbuild,
  version: "0.18.6",
  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. Note profiles must be configured in your
config/config.exs, as esbuild runs without starting your application
(and therefore it won't pick settings in config/runtime.exs).

Adding to Phoenix

To add esbuild to an application using Phoenix, you need only four steps. Installation requires that Phoenix watchers can accept module-function-args tuples which is not built into Phoenix 1.5.9.

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

def deps do
  [
    {:phoenix, github: "phoenixframework/phoenix", branch: "v1.5", override: true},
    {:esbuild, "~> 0.7", runtime: Mix.env() == :dev}
  ]
end

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

config :esbuild,
  version: "0.18.6",
  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"]

Third-party JS packages

If you have JavaScript dependencies, you have two options
to add them to your application:

1. Vendor those dependencies inside your project and
   import them in your "assets/js/app.js" using a relative
   path:

   import topbar from "../vendor/topbar"
   

2. Call npm install topbar --save inside your assets
   directory and esbuild will be able to automatically
   pick them up:

   import topbar from "topbar"
   

CSS

esbuild has basic support for CSS. If you import a css file at the
top of your main .js file, esbuild will also bundle it, and write
it to the same directory as your app.js:

import "../css/app.css"

However, if you want to use a CSS framework, you will need to use a separate tool.
Here are some options to do so:

• Use standalone Tailwind or
  standalone SASS. Both similar to
  esbuild.

• You can use esbuild plugins (requires npm). See Phoenix' official
  guide on using them.

License

Copyright (c) 2021 Wojtek Mach, José Valim.

esbuild source code is licensed under the MIT License.