Mix tasks for installing and invoking bun.
This is an adaptation of the Elixir esbuild installer made by Wojtek Mach and José Valim.
If you are going to build assets in production, then you add
bun as dependency on all environments but only start it
in dev:
def deps do
[
{:bun, "~> 1.4", runtime: Mix.env() == :dev}
]
endHowever, if your assets are precompiled during development, then it only needs to be a dev dependency:
def deps do
[
{:bun, "~> 1.4", only: :dev}
]
endOnce installed, change your config (i.e. config/config.exs or
config/runtime.exs) to pick your bun version of choice:
config :bun, version: "1.1.22"Now you can install bun by running:
$ mix bun.installAnd invoke bun with:
$ mix bun default assets/js/app.js --outdir=priv/static/assets/The executable is kept at _build/bun. You can access it directly to manage packages and many more things:
# Install a NPM package such a htmx.org
_build/bun add htmx.org
# Install a local package such as phoenix_html
_build/bun add ./deps/phoenix_html
# Remove a dependency
_build/bun remove htmx.orgThe first argument to bun is the execution profile.
You can define multiple execution profiles with the current
directory, the OS environment, and default arguments to the
bun task:
config :bun,
version: "1.1.22",
assets: [
args: [],
cd: Path.expand("../assets", __DIR__)
],
js: [
args: ~w(build js/app.js),
cd: Path.expand("../assets", __DIR__)
]When mix bun js is invoked, it will invoke bun build js/app.js
appending any argument given to the task. You can also use
mix bun assets to run any bun command in the assets directory.
To add bun to an application using Phoenix, you need only four steps. Installation requires that Phoenix v1.6+:
First add it as a dependency in your mix.exs:
def deps do
[
{:phoenix, github: "phoenixframework/phoenix"},
{:bun, "~> 1.4", runtime: Mix.env() == :dev}
]
endNow let's change config/config.exs to configure bun to add two commands,
one to install dependencies and another to build assets/js/app.js as an
entry point and write to priv/static/assets:
config :bun,
version: "1.1.22",
assets: [args: [], cd: Path.expand("../assets", __DIR__)],
js: [
args: ~w(build js/app.js --outdir=../priv/static/assets --external /fonts/* --external /images/*),
cd: Path.expand("../assets", __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:
bun_js: {Bun, :install_and_run, [:js, ~w(--sourcemap=inline --watch)]}Note we are inlining source maps and enabling the file system watcher.
Finally, back in your mix.exs, let's configure Phoenix assets tasks
to use bun instead:
"assets.setup": ["bun.install --if-missing"],
"assets.build": ["bun js"],
"assets.deploy": ["bun js --minify", "phx.digest"],By default, Phoenix comes with three JS libraries that you'll most likely use in your project: phoenix, phoenix_html and phoenix_live_view.
To tell bun about those libraries you will need to add the following to the assets/package.json file:
{
"workspaces": [
"../deps/*"
],
"dependencies": {
"phoenix": "workspace:*",
"phoenix_html": "workspace:*",
"phoenix_live_view": "workspace:*"
}
}and then configure mix assets.setup to install them:
"assets.setup": ["bun.install --if-missing", "bun assets install"],
Now run mix assets.setup and you are good to go!
You can use bun to build CSS with TailwindCSS, replacing both esbuild and the tailwindcss library in Elixir.
First, update assets/package.json:
"dependencies": {
"phoenix": "workspace:*",
"phoenix_html": "workspace:*",
"phoenix_live_view": "workspace:*",
"tailwindcss": "^4.1.0",
"@tailwindcss/cli": "^4.1.0",
"topbar": "^3.0.0"
}Update your :tailwind configuration in config/config.exs to use bun instead:
config :bun,
css: [
args: ~w(run tailwindcss --input=css/app.css --output=../priv/static/assets/app.css),
cd: Path.expand("../assets", __DIR__)
]Make sure to remove the :tailwind config in this file as well.
In config/dev.exs, replace the watchers:
bun_css: {Bun, :install_and_run, [:css, ~w(--watch)]}Update mix.exs aliases:
"assets.setup": ["bun.install --if-missing", "bun assets install"],
"assets.build": ["bun js", "bun css"],
"assets.deploy": ["bun css --minify", "bun js --minify", "phx.digest"],
Remove the tailwind and esbuild dependencies from your mix.exs.
If you have JavaScript dependencies, you have three 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
mix bun assets add topbarinside your assets directory andbunwill be able to automatically pick them up:import topbar from "topbar"
bun has support for CSS. If you import a css file at the
top of your main .js file, bun will also bundle it, and write
it to the same directory as your app.js:
import "../css/app.css"Copyright (c) 2023 Cristian Álvarez.
bun source code is licensed under the MIT License.