Mix tasks for installing and invoking esbuild.
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.2", 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.2", only: :dev}
]
end
Once installed, change your config/config.exs
to pick your
esbuild version of choice:
config :esbuild, version: "0.12.26"
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
.
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.26",
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
).
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.2", 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.12.26",
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"]
If you have JavaScript dependencies, you have two options to add them to your application:
-
Vendor those dependencies inside your project and import them in your "assets/js/app.js" using a relative path:
import topbar from "../vendor/topbar"
-
Call
npm install topbar --save
inside your assets directory andesbuild
will be able to automatically pick them up:import topbar from "topbar"
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, such as SASS or Tailwind, you will need to use a separate tool. Here are some options to do so:
-
You can use
esbuild
plugins (requiresnpm
). See Phoenix' official guide on using them. -
If you want SASS, you can bring standalone SASS to your project, without a need for external dependencies (similar to esbuild).
-
You can bring
Node
+npm
to your application and install any package you want. See this pull request on how to add Alpine + Tailwind.
Copyright (c) 2021 Wojtek Mach, José Valim.
esbuild source code is licensed under the MIT License.