Bun

Mix tasks for installing and invoking bun.

This is an adaptation of the Elixir esbuild installer made by Wojtek Mach and José Valim.

Installation

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.6", 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
  [
    {:bun, "~> 1.6", only: :dev}
  ]
end

Once 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.install

And 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.org

Profiles

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

Adding to Phoenix

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.6", runtime: Mix.env() == :dev}
  ]
end

Now 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"],

Phoenix JS libraries

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!

LiveView colocated JavaScript

When using Phoenix LiveView colocated JavaScript feature, the bundler needs to be configured to look for packages in the correct locations.

With esbuild, the Phoenix generator automatically sets up the NODE_PATH environment variable for you:

config :esbuild,
  my_app: [
    args:
      ~w(js/app.js --bundle --target=es2022 --outdir=../priv/static/assets/js --external:/fonts/* --external:/images/* --alias:@=.),
    cd: Path.expand("../assets", __DIR__),
    env: %{
      "NODE_PATH" => [Path.expand("../deps", __DIR__), Mix.Project.build_path()]
    }
  ]

To configure bun for colocated JavaScript, you need to tell LiveView where to write the colocated files. Unlike esbuild, which respects the NODE_PATH environment variable for module resolution, bun uses its own module resolution algorithm and does not recognize NODE_PATH. Instead, configure the :target_directory option in your config.exs to specify where LiveView should output colocated JavaScript files:

config :phoenix_live_view, :colocated_js,
  target_directory: Path.expand("../assets/node_modules/phoenix-colocated", __DIR__)

Replace esbuild with bun

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/css/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.

Third-party JS packages

If you have JavaScript dependencies, you have three 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 mix bun assets add topbar inside your assets directory and bun will be able to automatically pick them up:

   import topbar from "topbar"
   

CSS

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"

License

Copyright (c) 2023 Cristian Álvarez.

bun source code is licensed under the MIT License.