Late last year I joined a new company. In my first week, poking around the Phoenix app I’d be working on, I found this in config/test.exs:

config :bcrypt_elixir, :log_rounds, 1

Nobody on the team had written that line. The installer that scaffolded the app’s authentication generated it, as Phoenix’s own phx.gen.auth does for every new app. The bcrypt_elixir docs recommend the same thing plainly.

I winced. Only months earlier, at my previous company, I had spent weeks “discovering” this exact fix: profiling, benchmarks, rounds of factory rewrites, using the best available model at the time.

I even had a post drafted about that journey, documenting what felt like a solid performance win. It had been waiting on finishing touches I never got round to, and after that week they stopped mattering. So here it is instead, rewritten as a confession.

The Slow Suite

Rewind to my previous company. Our main Phoenix application had no reliable test suite. Some tests existed, but many failed for various reasons. That meant we couldn’t run them on CI, so they offered little assurance that new changes wouldn’t break existing functionality.

We were a tiny team, just three developers, hammered by an endless stream of feature requests and bug reports. My colleagues stayed underwater in that stream. But I kept coming back to the Chinese saying 工欲善其事，必先利其器: to do good work, one must first sharpen one’s tools. So I took the test suite on.

I fixed some failures, temporarily skipped others, and got the suite green. Then I set up a Jenkins pipeline so every change ran the tests. A real step forward, with a catch.

The full suite took 285 seconds on my laptop, and even longer on CI. Nearly five minutes per run meant I avoided running it locally, and every build was a long wait.

The slowness bothered me, but I had no clear picture of where the time was going and no obvious plan of attack. I couldn’t justify spending days on optimization without a concrete goal, so we lived with it for a long time.

What eventually changed the calculus was AI-assisted coding. With models finally capable of serious work on a real codebase, an open-ended optimization effort stopped looking like a time sink I couldn’t afford.

Finding the Bottleneck

Before optimizing anything, I profiled. The culprit revealed itself quickly: Bcrypt. Every call to Bcrypt.hash_pwd_salt() took 100–200ms.

That might not sound like much, until you realize the suite called it hundreds of times. Every insert(:user), insert(:customer), and insert(:provider) in our ExMachina factories hashed a password:

def user_factory() do
  %User{
    username: Internet.user_name(),
    email: Internet.email(),
    password_hash: Bcrypt.hash_pwd_salt("test_password_123")  # 100-200ms each!
  }
end

Multiply that by hundreds of test setups, and the bottleneck was clear.

Optimizing the Hard Way

The work happened in Claude Code, on Opus 4, the strongest model of the day. My instruction was direct: benchmark the factories and optimize away the repeated hashing.

And that is exactly what it did. Diligently. We pre-computed password hashes as module constants and reused them for all default test data, falling back to real hashing only for custom passwords:

defmodule Admin.UserFactory do
  # Pre-computed hash for the default test password
  @user_test_password "test_password_123"
  @user_test_password_hash "$2b$12$MFkURc/nMXU5HQxgWURhauA4tegLJKvJPlOtvQxzvQ35oz0q/Nrj2"

  def user_factory(attrs) do
    password = Map.get(attrs, :password, @user_test_password)

    # Use pre-computed hash for default, generate for custom passwords
    password_hash = Map.get_lazy(attrs, :password_hash, fn ->
      if password == @user_test_password do
        @user_test_password_hash  # Fast: pre-computed
      else
        Bcrypt.hash_pwd_salt(password)  # Slow: on-demand
      end
    end)

    %User{
      username: Internet.user_name(),
      email: Internet.email(),
      password_hash: password_hash
    }
  end
end

We applied this pattern across every authentication-related factory: users, customers, providers. Each got its own default test password and pre-computed hash.

The results?

# Before
$ mix test
....................................
Finished in 285.6 seconds

# After first optimization
$ mix test
....................................
Finished in 105.2 seconds

~63% improvement. Nearly three minutes off the suite. Success!

But notice what didn’t happen. The model knew the goal was a faster test suite, and, as I would soon find out, it knew the standard fix. Yet across all those rounds of benchmarking and refactoring, it never suggested log_rounds, or even checking the bcrypt_elixir docs. I had asked it to optimize factories, so it optimized factories.

And something felt wrong to me. We had added real complexity (constants, conditionals, helper functions across multiple factory files) for a problem that every Elixir app hashing passwords must share. A problem this common shouldn’t need solving the hard way.

The Question That Changed Everything

If the problem was that common, someone must have solved it properly already. So I asked a different question: “Is there a cheaper alternative to Bcrypt.hash_pwd_salt for tests?”

The model came back with the fix almost immediately: log_rounds. It had known all along. It was just never asked.

Bcrypt is intentionally slow. That’s the whole point: by making password hashing computationally expensive, it protects against brute-force attacks. The log_rounds parameter controls this cost:

• log_rounds: 12 means 2^12 = 4,096 iterations
• log_rounds: 10 means 2^10 = 1,024 iterations
• log_rounds: 4 means 2^4 = 16 iterations

Each increment doubles the computational work. The default of 12 is right for production. But test passwords are ephemeral: they exist only during a test run and are immediately discarded. They only need to be valid hashes, not brute-force resistant.

And crucially, log_rounds can be configured per environment:

# config/test.exs
config :bcrypt_elixir, :log_rounds, 4

One line. I reverted every factory change (the constants, the conditionals, the helpers) and the factories went back to their simple, original form:

def user_factory(attrs) do
  password = Map.get_lazy(attrs, :password, fn -> random_password() end)

  %User{
    username: Internet.user_name(),
    email: Internet.email(),
    password_hash: Bcrypt.hash_pwd_salt(password)  # Now fast!
  }
end

The results?

# After second optimization
$ mix test
....................................
Finished in 50.1 seconds

From 285 seconds to 50: an 82% speedup, 5.7× faster, with less code than we started with. Production and dev configs stayed at 12, so there was no security compromise anywhere.

It Shouldn’t Have Been a Discovery

I drafted this story a couple of months after the fix. Knowing no better, I had framed it as a reasonable approach to a tough problem, with a big discovery at the end. It needed only some finishing touches, but life got busy, and the draft sat.

Then came the new company, and that config line staring at me from a test.exs nobody had to write. I checked the bcrypt_elixir README. There it was: a low log_rounds setting for tests, documented clearly, all along.

I was taken aback. My hard-won discovery was just boilerplate, knowledge so standard that app generators write it for you. For a good while I wasn’t sure this post deserved publishing at all.

But that is exactly why it does. A tiny team lived with a five-minute test suite for years. The best model of the day ran rounds of benchmarks without once suggesting the docs. The fix was one documented line. The failure mode is the story.

What I Actually Learned

The bottleneck was the question, not the intelligence. The model knew about log_rounds the entire time. Any of us could have found it in the README in five minutes. Nobody asked.

AI amplifies your framing; it doesn’t correct it. Asked to optimize factories, the model optimized factories: skillfully, and entirely within my flawed premise. Knowing my end goal didn’t help; my instructions had already chosen the approach. The quality of the answer is capped by the quality of the question.

Read the library docs before optimizing around the library. Bcrypt was never the problem. Using production settings in tests was, and the library authors had anticipated exactly that.

Listen to the “this is too hard” feeling. The pre-computed-hash detour wasn’t wasted. The discomfort of all that added complexity is what pushed me to stop and ask a better question.

Config can beat code. If your Elixir test suite is slow and uses Bcrypt, the fix is one line, and if your app’s authentication came from a generator like phx.gen.auth, it is probably already there:

# config/test.exs
config :bcrypt_elixir, :log_rounds, 1

Generators write 1; the bcrypt_elixir docs suggest 4, which is what we used. Either way, hashing becomes effectively free in tests.

Sometimes the best optimization isn’t clever code, or even a smarter model. It’s noticing that a problem is too common to be this hard, then asking the question that assumes someone already solved it.

Examples below use a ZSA Moonlander (zsa/moonlander) and a keymap called mykeymap. Swap in your own board and keymap name as you go.

Quick start

1. Install the toolchain: curl -fsSL https://install.qmk.fm | sh
2. Fetch the QMK source: qmk setup (already have a clone? qmk config user.qmk_home=/path/to/qmk_firmware instead)
3. Sanity-check: qmk doctor (optional if you ran qmk setup, which runs it for you)
4. Keep your keymap in its own repo via External Userspace (details below)
5. Build: qmk compile -kb zsa/moonlander -km mykeymap
6. Flash: qmk flash -kb zsa/moonlander -km mykeymap, then drop the board into its bootloader.

Setting up QMK (recommended)

What you’re actually installing

The modern setup keeps everything tidy and self-contained, well away from your system Python and your day-to-day Homebrew packages. Three pieces get installed, all into user space:

• The qmk CLI, running inside its own uv-managed Python environment, so a Python upgrade somewhere else on your machine cannot break it.
• The compilers (ARM, AVR, RISC-V), as a prebuilt bundle that QMK maintains and ships itself. You do not have to hunt down cross-compilers or babysit their versions.
• The flashing utilities (dfu-util, avrdude, and friends), bundled right alongside.

When it is done, here is where things live by default, worth knowing so nothing feels like a black box:

• ~/.local/bin/qmk: the CLI, a symlink into ~/.local/share/uv/tools/qmk/
• ~/.local/bin/uv: the uv tool manager, if the script installed it
• ~/Library/Application Support/qmk/: the compilers and flashing tools
• ~/Library/Application Support/qmk/qmk.ini: your CLI config

1. Install the CLI and toolchains

One line does it:

curl -fsSL https://install.qmk.fm | sh

Yes, it is a curl … | sh, but it is the genuine official installer: all it does is fetch QMK’s bootstrap script and run it. It gives you a 10-second countdown before touching anything (hit Ctrl+C if you change your mind), then installs the three pieces above.

If you already have some of the prerequisites and do not want the installer fussing with them, you can opt out of individual steps. The handiest one on a machine already set up for development keeps it away from your Homebrew packages:

curl -fsSL https://install.qmk.fm | SKIP_PACKAGE_MANAGER=1 sh

SKIP_PACKAGE_MANAGER=1 stops the installer running brew update/brew upgrade, so it will not churn through your existing packages just to install a keyboard toolchain. (Already manage uv yourself? See Already manage uv yourself? below.)

Curious what else you can toggle? Run the installer with --help:

curl -fsSL https://install.qmk.fm | sh -s -- --help

One last thing before you move on: make sure ~/.local/bin is on your PATH, and ideally ahead of /opt/homebrew/bin, so the qmk you just installed is the one your shell actually reaches for. Drop this in your ~/.zshrc if it is not already there:

export PATH="$HOME/.local/bin:$PATH"

Then open a fresh shell and confirm with which qmk. You want to see /Users/you/.local/bin/qmk.

2. Tell the CLI where the QMK source lives

The CLI needs to know which qmk_firmware checkout to build from. That is the qmk_home setting.

If you do not have the QMK source yet, let QMK grab it for you (pass your GitHub fork’s username if you have one):

qmk setup

That clones the repo into ~/qmk_firmware, sets qmk_home, and runs qmk doctor to check things over.

Already cloned it somewhere of your own? Then skip qmk setup. Running it would just clone a redundant second copy. Point the CLI at what you have instead:

qmk config user.qmk_home=/Users/you/opensource/qmk_firmware

A quick read-back to confirm it stuck:

qmk config user.qmk_home

3. Check everything’s happy

qmk doctor

Think of this as your pre-flight check. A clean run means the CLI, the compilers, and qmk_home are all talking to each other. If something is missing or misconfigured, this is where it will tell you, much nicer than finding out halfway through a build.

4. Where to put your keymap

The recommendation here is External Userspace: keep your keymap in its own repository, completely outside the QMK tree. It is the approach that ages best: your personal config stays in a clean repo you own, and the QMK source stays pristine, so pulling in upstream updates never tangles with your changes.

The trick is that your external folder mirrors QMK’s own layout, so your keymap lives at:

<your-userspace>/keyboards/zsa/moonlander/keymaps/mykeymap/

You point QMK at the root of that userspace once:

qmk config user.overlay_dir=/path/to/your/userspace

From then on, the normal qmk compile command finds your keymap there automatically, with no difference in how you build. The full walkthrough, including how to scaffold the folder, lives in the QMK External Userspace docs.

If you would rather keep things dead simple and do not mind your keymap living inside the QMK checkout, the in-tree spot still works fine: drop the same keymaps/mykeymap/ folder under <qmk_home>/keyboards/zsa/moonlander/. A lot of people version just that folder as its own git repo to get some of the separation benefits. It is a perfectly good starting point for a single keymap. The snag shows up once you have more than one: because each keymap lives in its own folder, each becomes its own separate git repo, so managing several, possibly across different keyboards, means a repo to track for every one. Your keymaps also show up as local changes inside the QMK tree.

5. Build it

qmk compile -kb zsa/moonlander -km mykeymap

A green [OK] and a freshly generated .bin (or .hex on AVR boards) means you are good. You do not have to worry about the compiler being on your PATH. The CLI quietly wires up its bundled toolchain for you each time.

6. Flash it

qmk flash -kb zsa/moonlander -km mykeymap

This compiles and then sits waiting for your keyboard to show up in bootloader mode. To get a Moonlander there, do one of:

• Tap a QK_BOOT key, if your keymap has one mapped, or
• Press the physical reset button on top of the board.

The moment it enters the bootloader, qmk flash spots it and writes the firmware. Prefer a GUI? ZSA’s Keymapp flashes the same firmware without the command line.

Staying up to date

• The CLI is a uv tool, so uv tool upgrade qmk bumps it, or just re-run the install script.
• The toolchains refresh by re-running the install script whenever you want the latest bundle.
• The QMK source updates with a git pull in your qmk_home. Follow it with git submodule update --init --recursive to sync the submodules QMK pulls in. As long as you created your own keymap rather than updating the built-in keymaps in QMK, the pull stays conflict-free.

Already manage uv yourself?

If you already have uv installed, say via Homebrew or its standalone installer, there is no need to run the uv installer again. Pass SKIP_UV=1 so the QMK installer reuses the uv you already have:

curl -fsSL https://install.qmk.fm | SKIP_UV=1 sh

The only tradeoff is who owns updates: the qmk CLI still runs in its own uv-managed environment either way, but you keep uv itself current yourself (brew upgrade uv, or however you installed it) rather than re-running the QMK installer to refresh it.

If you set up QMK the old way (via Homebrew)

Most likely you installed qmk and the ARM/AVR compilers from a handful of third-party Homebrew taps (qmk/qmk, osx-cross/arm, osx-cross/avr). For years that was just a few brew tap and brew install commands that ran without fuss. But that has recently changed: Homebrew 6.0.0 introduced Tap Trust. Because a tap is a Git repo of Ruby that runs with your privileges, it now refuses to load a non-official tap until you have explicitly trusted it. It is a healthy change, it surfaces a trust decision that used to be made silently on your behalf, but it also turns the old setup into a fiddlier and slightly nervier process of vouching for several third-party sources before anything will install. The self-contained installer above sidesteps all of that, which is why the tap-based recipe has been retired.

Cleaning out the old Homebrew install

Do this after the modern setup is working (qmk doctor green and a successful compile), so you are never without a working build. The order matters: uninstall the formulae first, then remove the taps, then sweep up orphans.

brew uninstall --force qmk hid_bootloader_cli mdloader
brew uninstall arm-none-eabi-gcc@8 arm-none-eabi-binutils avr-gcc@8 avr-binutils
brew untap qmk/qmk osx-cross/arm osx-cross/avr
brew autoremove

A few notes so nothing surprises you:

• The --force on the first line clears out all installed versions at once.
• You cannot untap a tap while its formulae are still installed, which is why the untap comes after the uninstalls.
• brew autoremove mops up the long chain of dependencies the qmk formula originally dragged in (think Pillow → cairo/freetype/fonts, plus flashing tools like avrdude, dfu-util, dfu-programmer). It only removes things nothing else depends on, so shared tools like make, libusb, hidapi, python, and openssl stay put. Glance over its proposed list before confirming, and if you use something like dfu-util for non-QMK work, leave that one out of the uninstall.

Other gotchas you might run into

qmk: no such file or directory right after uninstalling. This one is a classic head-scratcher. zsh caches the full path of each command it has run, so after you delete a binary it keeps reaching for the old, now-gone path. Clear the cache and you are fine:

hash -r

(rehash works too, or just open a new terminal.)

qmk_home set to None, so you are building the wrong tree. If the CLI does not know where the QMK source lives, it falls back to ~/qmk_firmware, which might be empty or simply not the repo your keymap is in, and you will get baffling build results. Check it, then set it:

qmk config user.qmk_home
qmk config user.qmk_home=/Users/you/opensource/qmk_firmware

Quick reference

Where everything lives by default:

• CLI binary: ~/.local/bin/qmk, a symlink into ~/.local/share/uv/tools/qmk/
• Compilers and flashing tools: ~/Library/Application Support/qmk/
• CLI config: ~/Library/Application Support/qmk/qmk.ini
• QMK source: wherever user.qmk_home points
• Keymap (External Userspace): <overlay_dir>/keyboards/<vendor>/<board>/keymaps/<name>/
• Keymap (in-tree): <qmk_home>/keyboards/<vendor>/<board>/keymaps/<name>/

Handy sanity commands:

qmk doctor
which qmk
qmk config
qmk compile -kb zsa/moonlander -km mykeymap

Prerequisites

• Vim or Neovim with coc.nvim installed
• Elixir and Erlang installed (ideally managed via asdf)

Step 1: Install ElixirLS

Clone and build ElixirLS:

git clone https://github.com/elixir-lsp/elixir-ls.git ~/.elixir-ls
cd ~/.elixir-ls
mix deps.get
MIX_ENV=prod mix compile
MIX_ENV=prod mix elixir_ls.release2 -o release

The last command builds the executable language server to ~/.elixir-ls/release/, and that is the path we need to use in the coc.nvim configuration.

Step 2: Configure coc.nvim

Open your coc settings in Vim with :CocConfig and add:

{
  "elixir.pathToElixirLS": "~/.elixir-ls/release/language_server.sh"
}

Step 3: Install coc-elixir

In Vim, run:

:CocInstall coc-elixir

This installs the coc.nvim extension that communicates with ElixirLS.

Step 4: Verify

Open an Elixir file in your project. You should see:

• Autocomplete suggestions
• Inline diagnostics and warnings
• Go-to-definition working (:call CocAction('jumpDefinition'))

Understanding the .elixir_ls Directory

When you first open an Elixir project, ElixirLS creates a .elixir_ls/ directory and compiles your project. You might wonder why it doesn’t just use _build/.

ElixirLS maintains its own build for several reasons:

1. Avoids conflicts - Your _build/ uses your development environment. ElixirLS compiles separately so running mix test doesn’t invalidate the language server’s build.

2. Different compile options - ElixirLS uses flags that capture additional metadata for IDE features. These would slow down normal development builds.

3. Dialyzer PLT files - ElixirLS caches Dialyzer’s Persistent Lookup Table here. Building PLTs is slow, so caching them per-project saves time.

4. Independence - If your _build/ breaks, ElixirLS keeps working.

Consider adding .elixir_ls/ to your global gitignore:

echo ".elixir_ls/" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

Troubleshooting

If ElixirLS behaves unexpectedly, the simplest fix is to delete its cache and restart:

rm -rf .elixir_ls/

Then in Vim:

:CocRestart

ElixirLS automatically recreates the directory and recompiles when it restarts.

Common reasons to clear the cache:

• Upgraded Elixir or Erlang versions
• Dialyzer giving stale warnings
• Language server stuck or unresponsive
• Dependency changes not being picked up

As a developer, I use the terminal extensively and often SSH into remote machines for management tasks. When I connect via SSH, iTerm2 automatically updates both the window and tab titles to something like user@machine-ip:directory-name, which provides helpful context about where I’m working. The problem? These titles don’t automatically revert when I disconnect, leaving me with stale information in my terminal tabs.

For years, I had no idea what was happening under the hood, let alone how to fix it. My workaround was crude but effective: close the tab and open a new one. Eventually, I got fed up and decided to take some actions. After some research, I added this mysterious snippet to my .zshrc:

precmd() {
  # sets the tab title to current dir
  echo -ne "\e]1;${PWD##*/}\a"
}

I’ll be honest—I didn’t fully understand how it worked, but it did the job. This function “forced” my tab title to always display the current directory name, even after disconnecting from SSH sessions.

Later, I discovered Prezto, a configuration framework for Zsh that includes a handy set-tab-title function. This gave me more flexible control over tab titles, so I happily retired my hacky precmd solution.

You might have noticed that the window title remained untouched throughout this journey. It simply wasn’t annoying enough to warrant investigation—until Claude Code came along.

Since its public launch in February, Claude Code has become my go-to tool for AI-assisted coding. Like SSH, it helpfully sets custom tab and window titles to show what it’s working on. Also like SSH, these titles stick around after Claude Code exits, cluttering my terminal with outdated information like “Building Feature X…” or “Optimising test performance…” long after those tasks completed.

Since I was using Claude Code across multiple projects every day, these stale titles were starting to get on my nerves and that was the final straw. It was time to properly understand how terminal titles work and build a comprehensive solution.

Understanding Terminal Titles in iTerm2

Before diving into solutions, let’s understand what we’re dealing with. iTerm2 (and most terminal emulators) recognize two distinct title types:

1. Tab Title - Displayed on the individual tab
2. Window Title - Shown in the center of the window’s title bar

These titles are controlled through ANSI escape sequences - special character combinations that terminals interpret as commands rather than text to display.

The Magic Behind Terminal Titles

Here’s how escape sequences work for setting titles:

# Set window title only (shows in title bar)
echo -ne "\033]2;Your Window Title\007"

# Set tab title only (shows in tab)
echo -ne "\033]1;Your Tab Title\007"

# Set both window and tab to the same title
echo -ne "\033]0;Your Title\007"

The cryptic \033] starts the escape sequence, the number (0, 1, or 2) specifies which title to set, and \007 (the bell character) ends it.

Quick note on escape characters: You might see these written as \e (instead of \033) and \a (instead of \007) in some scripts—they’re equivalent, just different representations of the same ASCII characters. I’m using the octal format (\033 and \007) here for maximum compatibility across different shells and systems.

Simple, right? Well, not exactly intuitive and quite cumbersome to use, which is why we’re building a better interface.

The Solution: A Simple Title Manager

Let’s create a user-friendly function that makes title management a breeze. Add this to your ~/.zshrc (or ~/.bashrc for Bash users):

# Terminal title management functions
terminal_titles() {
    case "$1" in
        window)
            echo -ne "\033]2;$2\007"
            ;;
        tab)
            echo -ne "\033]1;$2\007"
            ;;
        both)
            echo -ne "\033]0;$2\007"
            ;;
        help)
            echo "Usage: terminal_titles [window|tab|both|reset|help] [title]"
            echo "  window [title] - Set window title only"
            echo "  tab [title]    - Set tab title only"
            echo "  both [title]   - Set both window and tab to same title"
            echo "  reset          - Reset to default titles"
            echo "  help           - Show this help message"
            echo "  (no args)      - Same as reset"
            ;;
        reset|"")
            # Window title: full path with ~ for home
            echo -ne "\033]2;${PWD/#$HOME/~}\007"
            # Tab title: last portion of the full path
            echo -ne "\033]1;${PWD##*/}\007"
            ;;
        *)
            echo "Unknown command: $1"
            echo "Use 'terminal_titles help' for usage"
            ;;
    esac
}

# Alias for convenience
alias tt='terminal_titles'

How to Use It

Now you have a simple tt command at your disposal:

# Reset titles to show current directory info
tt

# Set a custom window title
tt window "Development Server"

# Set a custom tab title
tt tab "logs"

# Set both to the same title
tt both "Project X"

# Get help
tt help

The default behavior (tt with no arguments) resets your titles to something useful:

• Window title: Full path of current directory (with ~ for home)
• Tab title: Just the current folder name

For example, if you’re in /Users/you/projects/awesome-app, the window shows ~/projects/awesome-app and the tab shows awesome-app.

Conclusion

After years of closing and reopening tabs to clear stale SSH titles, and more recently dealing with Claude Code’s persistent status messages, I finally have a solution that just works. The tt command is now muscle memory—quick to type, easy to remember, and does exactly what I need.

The beauty of this solution is its simplicity. No complex configurations, no heavyweight terminal managers—just a few lines of shell script that give you complete control. Whether you’re jumping between SSH sessions, running Claude Code throughout the day, or just want cleaner tab organization, you now have the tools to keep your terminal titles under control.

Happy terminal customizing! 🚀

Note: After building this solution, I discovered that Prezto actually has a set-window-title command hiding alongside the set-tab-title function I’d been using for years. Had I found it earlier, this entire journey into the depths of ANSI escape sequences might never have happened. But you know what? I’m okay with missing it. Sometimes the scenic route teaches you more than the shortcut ever could, and now I truly understand what’s happening under the hood rather than just blindly using a command.

Appendix: Auto-Reset with Smart Persistence

If you want titles to automatically reset after commands like Claude Code exit, but keep your manually-set titles, here’s an enhanced version with intelligent auto-reset. This adds more complexity but offers finer control:

# Terminal title management functions with smart auto-reset
terminal_titles() {
    case "$1" in
        window)
            echo -ne "\033]2;$2\007"
            export TERMINAL_TITLE_MANUAL=1
            ;;
        tab)
            echo -ne "\033]1;$2\007"
            export TERMINAL_TITLE_MANUAL=1
            ;;
        both)
            echo -ne "\033]0;$2\007"
            export TERMINAL_TITLE_MANUAL=1
            ;;
        help)
            echo "Usage: terminal_titles [window|tab|both|reset|auto|help] [title]"
            echo "  window [title] - Set window title only"
            echo "  tab [title]    - Set tab title only"
            echo "  both [title]   - Set both window and tab to same title"
            echo "  reset          - Reset to default titles"
            echo "  auto           - Enable auto-reset after commands"
            echo "  help           - Show this help message"
            echo "  (no args)      - Same as reset"
            ;;
        auto)
            unset TERMINAL_TITLE_MANUAL
            terminal_titles reset
            echo "Auto-reset enabled"
            ;;
        reset|"")
            # Window title: full path with ~ for home
            echo -ne "\033]2;${PWD/#$HOME/~}\007"
            # Tab title: last portion of the full path
            echo -ne "\033]1;${PWD##*/}\007"
            unset TERMINAL_TITLE_MANUAL
            ;;
        *)
            echo "Unknown command: $1"
            echo "Use 'terminal_titles help' for usage"
            ;;
    esac
}

# Alias for convenience
alias tt='terminal_titles'

# Auto-reset after commands ONLY if not manually set (for zsh)
if [[ -n "$ZSH_VERSION" ]]; then
    precmd() {
        # Only reset if titles weren't manually set
        if [[ -z "$TERMINAL_TITLE_MANUAL" ]]; then
            # Window title: full path with ~ for home
            echo -ne "\033]2;${PWD/#$HOME/~}\007"
            # Tab title: last portion of the full path
            echo -ne "\033]1;${PWD##*/}\007"
        fi
    }
fi

This enhanced version adds:

• Smart persistence: Manually-set titles survive command execution
• Auto-reset mode: Titles automatically update after commands (when not manually set)
• Flexible control: Switch between manual and automatic modes with tt auto

The Smart Workflow

1. Normal operation: Titles auto-update to show your current directory
2. Set custom title: tt tab "server logs" - This persists across commands
3. Return to auto-mode: tt auto or tt reset

A couple of weeks ago, we attempted to upgrade our Erlang/OTP version from 24 to 25.3.2.16, which was the latest release at the time. Unfortunately, shortly after the new release containing this change was deployed to production, our Customer Service team reported that a specific payment feature had stopped working. In fact, they noticed that we had stopped receiving this type of payment almost immediately after the new release hit production. The timing was too suspiciously close for this to be a coincidence.

The Investigation

When investigating this issue, I had no idea what the cause was, but I did have significant time pressure due to the nature of the problem—payments not being processed is always urgent!

First thing I did was to understand where the failure was happening and managed to replicate it in my local environment. Next, I methodically went through the all the changes in this release, reverting suspicious-looking changes one by one. Surprisingly, none of our actual code changes was the culprit.

The OTP version upgrade had seemed like one of the most innocent changes with regard to the payment issue we were facing. However, after exhausting other possibilities, I tested against OTP 24 since the OTP upgrade was a relatively major change in the same release. I was quite shocked to discover that the new version of OTP was indeed the guilty party.

The (Partial) Solution

Since I’m not an expert on certificate validation in Erlang, the error message we got when making requests to the bank looks cryptic:

TLS :client: In state :wait_cert_cr at ssl_handshake.erl:2123 generated CLIENT ALERT: Fatal - Unsupported Certificate
 - {:key_usage_mismatch,
 { {:Extension, {2, 5, 29, 15}, true, [:keyCertSign, :cRLSign]},
  {:Extension, {2, 5, 29, 37}, false,
   [{1, 3, 6, 1, 5, 5, 7, 3, 2}, {1, 3, 6, 1, 5, 5, 7, 3, 1}]}}}

But armed with this error message, I was able to find a Github issue in the official OTP repository about the same problem. Apparently other developers making HTTP requests with Erlang/Elixir had encountered the same issue.

Thanks to Ingela Andin, the maintainer, and the community’s efforts, a fix had already been released for OTP 26 and 27. But unfortunately for us, there was an impression that OTP 25 wasn’t affected, so no fix had been done for it. Given our urgent situation, we decided to revert back to OTP 24 to restore payment processing as quickly as possible.

It’s worth noting that after I reported that OTP 25 was indeed affected by the same issue, Ingela responded quickly and worked on backporting the fix. A new patch version with the fix was released about two weeks ago, clearing our path to safely upgrading to OTP 25.

Now that we had a solution, I wanted to better understand what caused the problem in the first place.

Understanding Digital Certificates

To understand the bug, we need a quick primer on SSL/TLS certificates: digital certificates are like digital ID cards that websites use to prove their identity. Each certificate contains:

• The website’s public key
• Information about the website (domain name, etc.)
• Information about how the certificate can be used
• A signature from a trusted Certificate Authority (CA)

Certificates have “extensions” that specify what they can be used for. Two important ones are:

• Key Usage (KU): Broadly defines what the certificate’s key can do (sign things, encrypt things, etc.)
• Extended Key Usage (EKU): More specifically defines the certificate’s purpose (web server authentication, email, etc.)

The Bug in OTP

The bug occurred because recent versions of OTP was enforcing a rule that wasn’t actually specified in the certificate standards (RFC 5280).

In simple terms:

• The certificates from certain CAs like Entrust had a flag set indicating they could sign other certificates (keyCertSign)
• They also had flags set saying they could be used for web server authentication
• OTP thought these two purposes were contradictory and rejected the certificate

It’s like if you’re qualified as both a teacher and a restaurant chef, but then a bureaucrat refused to accept because “you can’t possibly do both these unrelated jobs.” In reality, of course, there’s no reason someone couldn’t be qualified for both roles independently.

And same goes for digital certificates. The certificate standard (RFC 5280) allows certificates to serve multiple purposes simultaneously, but OTP’s new validation logic was too restrictive.

For those interested in further technical details, there are extensive discussions in the Github issue and here is the PR that fixed it.

Takeaways

A few interesting lessons from this experience:

1. Hidden Complexity: Even mature, well-tested software like Erlang/OTP can have subtle bugs in complex areas like SSL/TLS.
2. Implementation vs. Specification: The bug wasn’t a coding error but an overly strict interpretation of a technical standard.
3. Community Matters: Thanks to the Erlang community for identifying and fixing this issue very quickly.

Summary

In this post, we started with an unexpected payment issue in production from upgrading the OTP version to 25. After identifying the new OTP version as the culprit, we had to revert back to OTP 24.

We also dove into understanding how the bug happened, which was essentially an overly strict interpretation of certificate standards. Thanks to the responsive Erlang community and OTP maintainers, a fix was backported to OTP 25, resolving the bug.

For me this was quite an interesting experience, because the overwhelming majority of bugs we face as developers are introduced by ourselves in the application layer. Sometimes we do encounter bugs in the library or framework that we use, but that’s pretty rare. It is ultra rare to face a bug in the underlying programming language. In fact, this was the very first one I had in my whole career as a developer, and I’ve been doing this for almost 20 years.

In the production configuration files of this project, we have environment variable names interpolated in strings as follows:

# config/prod.exs
config :my_app, MyApp.Repo,
  hostname: "${DATABASE_HOSTNAME}",
  username: "${DATABASE_USERNAME}",
  ...

Clearly this approach wouldn’t work for the :dev environment, where we would typically see something like this:

# config/dev.exs
config :my_app, MyApp.Repo,
  hostname: System.get_env("DATABASE_HOSTNAME"),
  username: System.get_env("DATABASE_USERNAME"),
  ...

However, I also knew that the interpolation syntax did work for us in production. This made me curious: How exactly does this work? It was time for some investigation.

The How

After consulting with our old friend Google and chatting with our new friend GPT-4, I learnt that this peculiar method of setting configuration values from environment variables is facilitated by Distillery, the tool we use for building releases.

For this functionality to be enabled, the environment variable REPLACE_OS_VARS must be set to true. And then Distillery would replace environment variables with their actual values upon encountering interpolation syntax, such as "${DATABASE_USERNAME}", in the configuration files.

As a matter of fact, when it comes to handling application configuration, Distillery supports more than simple variable interpolation. It also supports Config Providers, which are custom modules capable of dynamically generating configuration at the start of your application. For further details, please refer to the relevant section in Distillery documentation.

The Why

While it’s enlightening to learn how it works, I kept wondering: why does Distillery offer support for both interpolation and Config Providers? Isn’t System.get_env good enough for this purpose? As it turns out, although System.get_env is quite effective for the :dev environment, it can be inadequate for the production environment in many cases.

To grasp this, we need to take a step back and have a quick review of how Elixir the language works. Elixir is a compiled language. When you execute mix compile, the Elixir compiler transforms your project into Erlang bytecode. This bytecode then runs on the Erlang Virtual Machine, commonly known as Bogdan/Björn’s Erlang Abstract Machine (BEAM).

The configuration files and code that are outside of function bodies within a module are evaluated at compile-time. Thus, if you use System.get_env("DATABASE_HOSTNAME") within a configuration file, it’s evaluated during the compilation process. This means the value of the environment variable DATABASE_HOSTNAME is then captured and embedded in the application as a static value.

For production configurations, the goal is generally to dynamically capture runtime environment variables, rather than to embedding those from the build server as static values. Apparently using System.get_env wouldn’t achieve this purpose.

That is precisely why Distillery supports both the interpolation syntax and Config Providers, enabling dynamic configuration value setting from the runtime environment of the application.

It’s noteworthy that with version 1.9, Elixir introduced built-in support for releases as well, which includes a novel approach to runtime configuration. This was achieved through the introduction of a new configuration file config/releases.exs, which is executed every time a release starts. Then in Elixir 1.11, another configuration file config/runtime.exs was introduced, which is essentially a superior version of config/releases.exs. For more details on these developments, please consult to the relevant documentation.

Summary

In this post, I shared my initial confusion about the interpolation syntax "${DATABASE_HOSTNAME}" in our production configuration files, followed by an exploration into understanding how it works and why is it necessary for runtime configuration. As always, my aim is to provide a reference for my further self and perhaps assist others along their journey.

  type StringOrNumber = string | number

Here the StringOrNumber type can be either string or number as expected. The member types do not have to be primitive types and they can be custom types as well.

When dealing with union types, before we can apply operations or functions that are specific to one member type, we would need to figure out which member type we have and that’s called type narrowing.

There are many ways to narrow the type, but in this post I specifically want to cover the syntax for creating a custom function to do type narrowing. I found myself referring back to the “Using type predicates” section on the Narrowing page in Typescript documentation, so I figure it might be a good idea to make it slightly easier to find and potentially easier to remember by writing a post about it.

Let’s say we want to create a type narrowing function for the StringOrNumber type above, it would look like this:

function isString(input: StringOrNumber): input is string {
  return typeof input === 'string'
}

Here, input is string is called a type predicate and it is the return type of the isString function. In the function body, it needs to return a boolean value: true means input is the expected type and false means it is not. The function’s logic can be as complex as it needs to be. As long as it returns a boolean value in the end, it’ll work fine as a type narrowing function or say a type guard.

In this example, returning true means input is a string, otherwise it’s a number, considering it can only be either a string or a number.

We can use it like the following:

// assuming we have a function that returns a string or a number
let a: StringOrNumber = getStringOrNumber()

if (isString(a)) {
  a.length
} else {
  a + 3
}

Of course, this is just a contrived example to demonstrate the correct syntax. In a real world application, we would most likely just do typeof input === 'string' instead of creating a function to do it.

One more thing worth noting is that when we create a custom type guard, Typescript would treat us as adults and completely trust that it will do the right thing. For example, we can define a nonsensical type guard like this:

function isString(input: StringOrNumber): input is string {
  return typeof input === 'number'
}

And Typescript would happily accept it and gives no compiler error or warning, but since it’s narrowing the type incorrectly, some runtime errors should be expected after using this type guard.

In this post, I briefly talked about what type narrowing is and then looked into how to define our own type guard. As usual, the hope is to help my future self and potentially be of service to other people who are starting their Typescript journey as well.

When trying to understand macros, I use the slightly different mental model: a macro is like a template with a name that can optionally have parameters; when the name is used, it’s substituted by the template with “values” of the arguments injected.

Sorry if it didn’t make it better. I’ll try to explain what do I mean by that. But let’s first review how C macros work.

C Macos

Before actually compiling a C program, the C compiler will use the C preprocessor to transform the program, which is also referred to as preprocessing. One of the things that happens in this preprocessing step is macro expansion.

In GNU’s online documentation for the C Preprocessor, a macro is defined as following:

A macro is a fragment of code which has been given a name. Whenever the name is used, it is replaced by the contents of the macro.

You can define a macro like this:

#define DOUBLE(x) (2 * x)

NOTE: by convention macro names in C use uppercase.

And then use it as below:

DOUBLE(5)

During preprocessing, the preprocessor will replace it with (2 * x). The compiler would just see (2 * x) as if you wrote it in stead of DOUBLE(5) in the first place.

So a macro in C allows us to define a fragment of code that can have parameters, and when it’s used the macro name would be replaced by the code fragment we defined with arguments interpolated.

It’s worth noting that since this happens before compilation, the program is still just a piece of text, so both arguments interpolation and macro expansion are just literal text substitution.

How does this relate to Elixir’s macros? Well macro expansion in Elixir is definitely not text substitution, but it’s still substitution, just happens at a higher level.

The Abstract Syntax Tree (AST)

Most programming languages have the Abstract Syntax Tree (AST), which is a tree structure the compiler builds from the source code before turning it into either machine code or byte code.

In most languages, the AST is not exposed to us developers and we can get our code working without worrying about the AST or even knowing about it.

In the case of Elixir, the compiler give us access to the AST. This comes with great power and allows us to do many things that aren’t possible in other languages, creating macros among them.

You can get the AST for a piece of code by using quote, for example:

iex(1)> quote do
...(1)> 1 + 2
...(1)> end
{:+, [context: Elixir, import: Kernel], [1, 2]}

This is probably the simplest form, but in general Elixir’s AST is represented as a three elements tuple. When the expression is more complex, its corresponding AST is usually deeply nested.

In Elixir, the AST is also known as quoted expressions.

For more details on working with quoted expressions, please refer to offical Quote and unquote guide.

Macros in Elixir

One thing to remember about macros in Elixir is that they receive AST as arguments and return AST.

You can define a macro with defmacro:

defmodule MyIf do
  defmacro if(condition, do: action) do
    quote do
      case unquote(condition) do
        x when x in [false, nil] -> nil
        _ -> unquote(action)
      end
    end
  end
end

Then you can use it by:

require MyIf

MyIf.if true, do: IO.puts("Hello world!")

# or

MyIf.if false, do: IO.puts("Will not print anything")

Mental models about Macros

Tree Metaphor

To understand how macros work in general, I often use the tree metaphor. The entire program is just a big tree containing data and expressions as nodes, some of which are macro usages. This is literally correct with Elixir, because the compiler do convert the program into a big abstract syntax tree in the form of a deeply nested three elements tuple.

Defining a macro is like creating a template in AST or say a sub-tree. If there are arguments, they can be injected to the sub-tree with unquote.

During macro expansion, the Elixir compiler will replace each macro usage node with the AST sub-tree returned by its macro definition with the arguments injected. Because macros can be used inside another macro, macro expansion will happen repeatedly until there are no more macros.

If we compare Elixir macros with C macros, we can see that they both offer a way to substitute an expression with a template. The difference is that in C we define the template as text and replaced as text, whereas in Elixir, the template is defined as a piece of AST and the substitution happens at the AST level as well.

Copy-Paste Metaphor

To figure out what a particular macro does, I usually think of it as copying what the macro definition has and pasting it where the macro is being used. For unquoted arguments, mentally replace them with the corresponding values passed in.

When the macro is more complex, this might not work, but it should still set one on the right path in understanding the macro.

Summary

Macros are hard and they can be daunting even for experienced developers.

In this short post, I tried to offer a different perspective in understanding macros in Elixir.

It would fantastic if this makes it slightly easier for someone to learn about macros.

If you’d like to learn more about Elixir macros, check out Saša Jurić’s great blog post series Understanding Elixir Macros and Chris Mccord’s book Metaprogramming Elixir.

The Pi-hole® is a DNS sinkhole that protects your devices from unwanted content, without installing any client-side software.

Pi-hole is a great piece of software if you are interested in a bit more privacy and saving some bandwidth at the same time.

As its name suggests, it can obviously be installed on a Raspberry Pi, but apart from that it actually runs on other Linux hardware as well. As long as your device can run one of the Officially supported Operating Systems, you should be able to run Pi-hole on it.

While supporting other hardware definitely has its use cases, I consider Raspberry Pi to be the best choice for running Pi-hole in the home network, because of its low cost and very low power consumption.

I happen to have a Raspberry Pi Zero that’s been collecting dust since I bought it a few years ago, which is perfect for running Pi-hole.

Install OS on Raspberry Pi

Obviously we need to install an operating system on Raspberry Pi before we could do anything with it.

The recommended way of installing an operating system for Raspberry Pi is to use the Raspberry Pi Imager. You’ll need a computer with an micro SD card reader to install an OS image on your card.

I’m running it on macOS, but it supports Linux and Windows as well. Just make sure to download the correct version for your OS.

Click CHOOSE OS to choose from a list of options. I’d recommended just go with Raspberry Pi OS (32-bit), which is the first option, unless you have a specific purpose for the Pi and you know what you are doing.

Then click CHOOSE STORAGE to select the mounted micro SD card. Remember that the imager will erase the card first, so you’ll lost everything on the card. Make sure you’ve got backup for anything you still need on the card.

Lastly, click WRITE to install the selected OS on your card.

For most of the OS options, the imager will download the OS image while writing it to the micro SD card. If you have a slow Internet connect, you can also download the OS image separately from the Raspberry Pi OS download page and then choose Use custom for the OS option and select the downloaded .img file.

Advanced options for the imager

There is also an “Advanced” menu in the imager, which you can open with Ctrl-Shift-X. This menu allows you to perform tasks like enabling SSH and setting admin password. As described in the next section, we can do those with terminal commands too.

Setup Raspberry Pi

Since I find connecting a monitor, a keyboard and a mouse to the Raspberry Pi quite cumbersome, I’d like to setup a headless Raspberry Pi.

In order to achieve that, there are a couple more things to do before booting the Raspberry Pi: enable SSH access and allow auto WiFi connection.

Enable SSH access

On macOS, the SD card with Raspberry Pi OS image is usually mounted on /Volumes/boot.

We can enable SSH by creating an empty file named ssh in the root directory of the card:

cd /Volumes/boot
touch ssh

Auto WiFi connection

I’d also like the Pi to be able to connect to WiFi when it boots up.

In order to do that, create a text file named wpa_supplicant.conf with the following content:

country=<your-country-code>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
network={
    ssid="<your-wifi-ssid>"
    psk="<your-wifi-psk"
    key_mgmt=WPA-PSK
}

Obviously, fill in the ISO 3166 alpha-2 country code of your country, your WiFi SSID and PSK.

Then copy the file to the root directory of the SD card:

cp wpa_supplicant.conf /Volumes/boot

Note: if you are using an older Raspberry Pi (like my Pi Zero), it might not support 5GHz networks

Connect via SSH

After the two steps above, we can put the SD card in the Raspberry Pi and boot it up.

Once it’s up and running, we should be able to connect to it via SSH:

ssh pi@<ip_for_raspberry_pi>

The default password is raspberry.

Make sure to update the admin password with passed after logging in.

Fix locale

When you run commands on the Raspberry Pi, you may see warnings like this

-bash: warning: setlocale: LC_ALL: cannot change locale (en_US.UTF-8)

So you might want to fix the locale.

If you are comfortable with vi or nano, just edit /etc/locale.gen and uncomment the line starting with en_US.UTF-8.

Otherwise you can run the following command to do the same:

perl -pi -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/g' /etc/locale.gen

Then run the following:

locale-gen en_US.UTF-8
update-locale en_US.UTF-8

After that, the annoying warnings should be gone.

Check out Jared Wolff’s post for more details on locale.

Install Pi-hole

Now the Raspberry Pi is in a reasonable state, we are ready to install Pi-hole.

The most convenient way to is to use the following command:

curl -sSL https://install.pi-hole.net | bash

The installation process is relatively straightforward. Just follow the prompts to get it done.

If you’d like to know what the installation script actually does, check out the source code basic-install.sh.

Take advantage of Pi-hole in the network

After Pi-hole is successfully installed, we still need to configure the router to use Pi-hole as the DNS server, which makes sure that all devices on the network will be protected automatically by Pi-hole.

If that’s not supported by your router or you only want certain devices to use Pi-hole, you can configure the DNS server on each device.

You might want to check out this comprehensive guide on the different options to configure Pi-hole as your DNS server.

Manage blocklists

Pi-hole comes with a default blocklist:

https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts

Which is well maintained and provides good protection without breaking normal functionality in most cases. For many this might be enough, but if you have other requirements, such as blocking adult content or targeted ads, you can add custom blocklists for improved blocking capabilities.

Check out The Best PiHole Blocklists (2021) for some blocklist options and more importantly, what to think about when choosing a blocklist.

You can add/remove blocklists under Group Management -> Adlists in the Pi-hole admin interface. After making changes there, you’ll need to either run pihole -g in terminal or go to Tools -> Update Gravity and click the Update button.

Whitelist Youtube history and etc

With the default blocklist from Pi-hole, the only thing that no longer works for me is Youtube history on iOS devices.

Adding a domain to the whitelist would solve that:

pihole -w s.youtube.com

Or if you prefer the admin interface, you can add a domain in Whitelist.

If you find other sites or services not working properly after introducing Pi-hole, you might want to check out the Commonly Whitelisted Domains and potentially whitelist relevant domains.

Keep software up-to-date

Last but not least, keeping things up-to-date on the Raspberry Pi would be a good idea.

Since Raspberry Pi OS is based on Debian Linux, we can use apt for that:

sudo apt update
sudo apt full-upgrade

Also we can remove packages that are no longer required with:

sudo apt autoremove

Summary

In this post, I walked through how to install Raspberry Pi OS, setup headless Raspberry Pi, install Pi-hole, manage blocklists and etc.

As many of my other posts, the main purpose is to serve as a reference for my future self. But if someone else finds it helpful too, I’d be very glad :slightly_smiling_face:

True that it’s just the first release candidate, but we are still one step closer to the formal release.

Update (28 September 2021): Phoenix 1.6.0 was released three days ago on 25 September, so now we do have our formal release

Last week, I managed to upgrade my little side project Rubik’s Cube Algorithms Trainer to Phoenix 1.6 and I’ll share my journey in this post. For the most part, I was following the Phoenix 1.5.x to 1.6 upgrade instructions by Chris McCord.

If you prefer watching a video than reading, I also did a talk about it at Elixir Sydney September 2021 meetup and the recording is on Youtube.

Update dependencies in Mixfile

First we need to update the dependencies in the mix.exs file:

def deps do
  [
    {:phoenix, "~> 1.6.0"},
    {:phoenix_html, "~> 3.0"},
    {:phoenix_live_view, "~> 0.16.0"},
    {:phoenix_live_dashboard, "~> 0.5"},
    {:telemetry_metrics, "~> 0.6"},
    {:telemetry_poller, "~> 0.5"},
    ...
  ]
end

Then run mix deps.get to install the new dependencies.

Two thing to note here:

• For phoenix, the override: true option is important, because Phoenix 1.6 is still in RC (This is no longer the case, since Phoenix 1.6.0 has been released)
• If you want to use the new HEEx templates, add phoenix_live_view even if you don’t actually use live view

esbuild for Javascript and CSS bundling (optional)

Next step is to use esbuild for Javascript and CSS bundling. This is an optional step in upgrading to Phoenix 1.6, but it is what I’m all excited about, so it’s not optional for me :smirk:

Phoenix asset pipeline overview

Before jumping into replacing webpack with esbuild, it’s worth having a quick review of the existing Phoenix asset pipeline:

• All static assets are served from priv/static
• Javascript: webpack bundles from assets/js to priv/static/js
• CSS: webpack bundles from assets/css to priv/static/css
• Images and other assets: webpack copies from assets/static -> priv/static

Now with the new asset pipeline based on esbuild, all static assets are still served from priv/static directory, so the first item stays the same.

With webpack gone, the other three obviously will change. For JS and CSS, esbuild will handle them; but we do need to deal with images and other assets separately.

Alright, let’s dive into how to make those changes.

Remove webpack config and related node files

First we need to remove webpack config and related node files:

$ cd assets
$ rm webpack.config.js package.json
     package-lock.json .babelrc
$ rm -rf node_modules

If you use yarn, remove yarn.lock instead of package-lock.json.

Add esbuild in deps

Then add esbuild as a dependency:

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

Configure esbuild

Next add configuration for esbuild in config/config.exs:

# config/config.exs
config :esbuild,
  version: "0.12.18",
  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__)}
  ]

Note: here we are providing the relative path from config to assets with the :cd option, so that the esbuild command can be run in the assets directory. Given that, if you have a umbrella app, the path should be something like ../apps/your_web_app/assets.

Update watcher in endpoint configuration

In your config/dev.exs file, there should be a node watcher that uses webpack under the endpoint configuration. We want to replace that one with the esbuild watcher below:

# config/dev.exs
config :your_web_app, YourWebApp.Endpoint,
  ...,
  watchers: [
    esbuild: {Esbuild, :install_and_run, [:default, ~w(--sourcemap=inline --watch)]}
  ]

Note: this is for local development only.

Move images and other assets

Then we deal with images.

The following is not mentioned in the Phoenix 1.6 upgrade instructions, but I found José Valim’s recommendation in a reddit thread.

He recommends to move everything in assets/static to priv/static; stop ignoring priv/static and commit it in version control; also ignore priv/static/assets instead, since that’s where esbuild puts the compiled Javascript and CSS files.

Add assets.deploy mix alias

Then we add a new mix alias for deployment:

defp aliases do
  [
    ...,
    "assets.deploy": ["esbuild default --minify", "phx.digest"]
  ]
end

As we can see, it has two parts:

1. esbuild will create minified Javascript and CSS and put them in priv/static/assets
2. the phx.digest task will add digests for all static assets priv/static

This is for deployment, so we only need to run it on build servers. For example when deploying to Heroku or the like, make sure it is run.

If you did run it locally, it would generate a whole bunch of digested assets. Since we no longer ignore priv/static, they would show up when you run git status for example and could be annoying.

We can remove them with the following command:

mix phx.digest.clean --all

Update layouts

As mentioned in the last section, esbuild puts compiled Javascript and CSS in priv/static/assets directory, so we need to update the references to them in the layouts, usually in app.html.eex or root.html.eex:

# update
Routes.static_path(@conn, "/js/app.js")
Routes.static_path(@conn, "/css/app.css")
# to
Routes.static_path(@conn, "/assets/app.js")
Routes.static_path(@conn, "/assets/app.css")

Update Plug.Static configuration

Last step for the new asset pipeline is to update configuration for Plug.Static.

We need to add the new assets directory in the :only option and also remove js and css from there since we no longer have them.

plug Plug.Static,
  at: "/",
  from: :my_app,
  gzip: false,
  only: ~w(assets fonts images favicon.ico robots.txt)

With the changes above, the new asset pipeline should be working, which means we are officially free of webpack and node in our Phoenix application :tada:

Migrate to HEEx templates (optional)

With Phoenix 1.6 the leex templates are deprecated and there is a new HEEx engine, which is being used in all the HTML files generated by phx.new, phx.gen.html etc.

It is HTML-aware and it enforces valid markup. It’s also more strict for the Elixir expressions inside tags.

In order to use it in an existing Phoenix project, make sure phoenix_live_view is added as a dependency, because the HEEx engine is part of phoenix_live_view.

Then rename all the existing .html.eex and .html.leex templates to .html.heex

Update Elixir expressions

When Elixir expressions appear in the body of HTML tags, HEEx templates use <%= ... %> for interpolation just like EEx templates.

So code in the following example stays the same:

<h2>Hello <%= @name %></h2>

<%= Enum.map(names, fn name -> %>
  <li><%= name %></li>
<% end) %>

But when an Elixir expression is used inside a tag, as the attribute value for example:

<div id="<%= @id %>">

It needs to be updated to:

<div id={@id}>

Notice the EEx interpolation is inside double quotes, the curly braces are not. So the Elixir expression has to serve as the whole attribute value, not part of it.

With EEx, the Elixir expression can serve as part of the attribute value:

<a href="/prefix/<%= @item.text %>">

In situations like this, directly replacing it with a pair of curly braces won’t work.

# this doesn't work
<a href="/prefix/{@item.text}">

One way I could think of is to interpolate the original Elixir term in a string and then put that string in a pair of curly braces like the following:

<a href={"/prefix/#{@item.text}"}>

Now the resulting string is the Elixir expression and it serves as the whole attribute value, so this works.

After making those changes, the new HEEx templates should be working.

Deployment

There are changes to the deployment process as well and I’ll cover that for Gigalixir, since that’s where my app is deployed to. But if you use Heroku, the changes should be fairly similar.

Since we no longer use webpack and node to build assets, phoenix_static_buildpack is not necessary any more. We can just get rid of it.

Also we need to make sure the assets.deploy task is run during deployment. We can use hook_post_compile in Elixir buildpack for that.

Just add this line in your elixir_buildpack.config:

hook_post_compile="eval mix assets.deploy && rm -f _build/esbuild"

With those two changes, my app can be deployed to Gigalixir without any issue.

If you’d like to deploy a new Phoenix 1.6 app to Gigalixir, check out the full guide.

New generators

I’d like to quickly mention that Phoenix 1.6 also ships with two new generators:

• phx.gen.auth generates a complete authentication solution for your application
• phx.gen.notifier generates a notifier for sending emails

In my little app, I didn’t need to use them. But if you do need an authentication solution or a notifier, check them out.

Summary

The release of Phoenix 1.6 is quite exciting, because by default webpack and node is replaced by esbuild. Now we can focus on developing the application in Elixir and Phoenix, without wasting time on breaking changes and nonsense security alerts in node dependencies.

In this post, I walked through how I upgraded my humble little Phoenix app to 1.6, with a focus on updating the asset pipeline to use esbuild and migrating to HEEx templates. Hope this helps someone who’s trying to do the same.

Phoenix 1.6 do have other new features that are not covered in this post. For those, make sure to check out the release note.