Elixir Best Practices

Elixir Best Practices

A collection of guiding principles and patterns for writing idiomatic Elixir and Phoenix applications, covering OTP, Ecto, and functional programming.

These guidelines aim to help developers:

• Write code that aligns with established Elixir best practices
• Apply consistent patterns across OTP, Phoenix, and Ecto
• Understand why certain approaches are preferred in the ecosystem
• Refactor toward idiomatic solutions
• Make informed architecture decisions

When reviewing or writing Elixir code, consider leveraging the broader ecosystem: Phoenix, Docker, PostgreSQL, Tailwind CSS, LeftHook, Sobelow, Credo, Ecto, ExUnit, Plug, Phoenix LiveView, Phoenix LiveDashboard, Gettext, Jason, Swoosh, Finch, DNS Cluster, File System Watcher, Release Please, and ExCoveralls.

Elixir Language Patterns

Pattern Matching

Pattern matching is fundamental to Elixir. Use it for:

Function clauses:

def greet(%User{name: name, role: :admin}), do: "Hello Admin #{name}"
def greet(%User{name: name}), do: "Hello #{name}"
def greet(_), do: "Hello stranger"

Case statements:

case {status, data} do
  {:ok, %{id: id} } when id > 0 -> process(id)
  {:error, reason} -> handle_error(reason)
  _ -> :unknown
end

With statements for chaining:

with {:ok, user}  0, do: :positive
def categorize(n) when is_integer(n) and n ` improves readability:

```elixir
# Instead of nested calls
result = String.trim(String.downcase(String.reverse(input)))

# Use pipes
result =
  input
  |> String.reverse()
  |> String.downcase()
  |> String.trim()

Pipe into case for handling results:

user_id
|> fetch_user()
|> case do
  {:ok, user} -> process_user(user)
  {:error, :not_found} -> create_user()
  {:error, reason} -> {:error, reason}
end

OTP (Open Telecom Platform) Patterns

GenServer

GenServer is the foundation for stateful processes:

defmodule Counter do
  use GenServer

  # Client API
  def start_link(initial_value) do
    GenServer.start_link(__MODULE__, initial_value, name: __MODULE__)
  end

  def increment do
    GenServer.cast(__MODULE__, :increment)
  end

  def get do
    GenServer.call(__MODULE__, :get)
  end

  # Server Callbacks
  @impl true
  def init(initial_value) do
    {:ok, initial_value}
  end

  @impl true
  def handle_cast(:increment, state) do
    {:noreply, state + 1}
  end

  @impl true
  def handle_call(:get, _from, state) do
    {:reply, state, state}
  end
end

Supervisor

Supervisors manage process lifecycles:

defmodule MyApp.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      # Database
      MyApp.Repo,

      # PubSub
      {Phoenix.PubSub, name: MyApp.PubSub},

      # GenServers
      {MyApp.Cache, []},
      {MyApp.Worker, []},

      # Endpoint (starts web server)
      MyAppWeb.Endpoint
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

Supervisor strategies:

• :one_for_one - restart only failed child
• :one_for_all - restart all children if one fails
• :rest_for_one - restart failed child and those started after it

Agent

For simple state management:

{:ok, agent} = Agent.start_link(fn -> %{} end)
Agent.update(agent, fn state -> Map.put(state, :key, "value") end)
Agent.get(agent, fn state -> Map.get(state, :key) end)

Phoenix Framework

Controllers

defmodule MyAppWeb.UserController do
  use MyAppWeb, :controller

  def index(conn, _params) do
    users = Accounts.list_users()
    render(conn, :index, users: users)
  end

  def create(conn, %{"user" => user_params}) do
    case Accounts.create_user(user_params) do
      {:ok, user} ->
        conn
        |> put_flash(:info, "User created successfully")
        |> redirect(to: ~p"/users/#{user}")

      {:error, %Ecto.Changeset{} = changeset} ->
        render(conn, :new, changeset: changeset)
    end
  end
end

Phoenix LiveView

For real-time interactive UIs:

defmodule MyAppWeb.CounterLive do
  use MyAppWeb, :live_view

  @impl true
  def mount(_params, _session, socket) do
    {:ok, assign(socket, count: 0)}
  end

  @impl true
  def handle_event("increment", _params, socket) do
    {:noreply, update(socket, :count, &(&1 + 1))}
  end

  @impl true
  def render(assigns) do
    ~H"""
    
      Count: 
      +
    
    """
  end
end

PubSub for broadcasting:

# Subscribe
Phoenix.PubSub.subscribe(MyApp.PubSub, "updates")

# Broadcast
Phoenix.PubSub.broadcast(MyApp.PubSub, "updates", {:new_data, data})

# Handle in LiveView
@impl true
def handle_info({:new_data, data}, socket) do
  {:noreply, assign(socket, :data, data)}
end

Channels

For WebSocket communication:

defmodule MyAppWeb.RoomChannel do
  use MyAppWeb, :channel

  @impl true
  def join("room:" <> room_id, _payload, socket) do
    {:ok, assign(socket, :room_id, room_id)}
  end

  @impl true
  def handle_in("new_message", %{"body" => body}, socket) do
    broadcast!(socket, "new_message", %{body: body})
    {:reply, :ok, socket}
  end
end

Ecto Database Patterns

Schemas and Changesets

defmodule MyApp.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset

  schema "users" do
    field :name, :string
    field :email, :string
    field :age, :integer

    has_many :posts, MyApp.Content.Post
    timestamps()
  end

  def changeset(user, attrs) do
    user
    |> cast(attrs, [:name, :email, :age])
    |> validate_required([:name, :email])
    |> validate_format(:email, ~r/@/)
    |> validate_number(:age, greater_than: 0)
    |> unique_constraint(:email)
  end
end

Queries

import Ecto.Query

# Basic queries
query = from u in User, where: u.age > 18, select: u

# Composable queries
def for_age(query, age) do
  from u in query, where: u.age > ^age
end

def ordered(query) do
  from u in query, order_by: [desc: u.inserted_at]
end

# Chain them
User
|> for_age(18)
|> ordered()
|> Repo.all()

# Joins and preloads
from u in User,
  join: p in assoc(u, :posts),
  where: p.published == true,
  preload: [posts: p]

Transactions

Repo.transaction(fn ->
  with {:ok, user}  Repo.rollback(reason)
  end
end)

Testing with ExUnit

defmodule MyApp.AccountsTest do
  use MyApp.DataCase, async: true

  describe "create_user/1" do
    test "creates user with valid attributes" do
      attrs = %{name: "John", email: "john@example.com"}
      assert {:ok, user} = Accounts.create_user(attrs)
      assert user.name == "John"
    end

    test "returns error with invalid email" do
      attrs = %{name: "John", email: "invalid"}
      assert {:error, changeset} = Accounts.create_user(attrs)
      assert %{email: ["has invalid format"]} = errors_on(changeset)
    end
  end
end

# Testing LiveView
defmodule MyAppWeb.CounterLiveTest do
  use MyAppWeb.ConnCase
  import Phoenix.LiveViewTest

  test "increments counter", %{conn: conn} do
    {:ok, view, _html} = live(conn, "/counter")
    assert view |> element("button") |> render_click() =~ "Count: 1"
  end
end

Deployment Best Practices

Releases

Use Elixir releases for production:

# mix.exs
def project do
  [
    releases: [
      myapp: [
        include_executables_for: [:unix],
        steps: [:assemble, :tar]
      ]
    ]
  ]
end

Build and deploy:

MIX_ENV=prod mix release
_build/prod/rel/myapp/bin/myapp start

Configuration

# config/runtime.exs
import Config

if config_env() == :prod do
  database_url = System.get_env("DATABASE_URL") ||
    raise "DATABASE_URL not available"

  config :myapp, MyApp.Repo,
    url: database_url,
    pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")
end

Health Checks

# In your router
get "/health", HealthController, :check

# Controller
def check(conn, _params) do
  case Repo.query("SELECT 1") do
    {:ok, _} -> send_resp(conn, 200, "ok")
    _ -> send_resp(conn, 503, "database unavailable")
  end
end

Consolidated Skills

This best practices skill consolidates 1 individual skill:

• elixir-best-practices

Iron Laws

1. ALWAYS use pattern matching and guards for control flow instead of nested if/case — idiomatic Elixir communicates intent through pattern matching; imperative conditionals fight the language.
2. NEVER use shared mutable state — always communicate through message passing between processes; shared mutable state in Elixir requires explicit ETS or Agent, which should be the exception not the rule.
3. ALWAYS use supervision trees for fault tolerance — never spawn bare processes that aren't supervised; unsupervised processes crash silently without recovery.
4. NEVER use Enum functions on potentially large streams — use Stream for lazy evaluation to avoid loading entire collections into memory.
5. ALWAYS write doctests (iex> examples in @doc) for public functions — doctests are runnable specifications; they document behavior and serve as regression tests.

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | ------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | Nested if/cond chains instead of pattern matching | Harder to read; misses the power of Elixir's pattern matching; doesn't scale | Use function clauses with pattern matching heads and guard clauses | | Bare spawn without supervision | Crashed processes disappear silently; no restart, no visibility | Always use Supervisor trees; use Task.Supervisor for dynamic tasks | | Enum.map/filter on large streams | Loads entire collection into memory; causes OOM on large datasets | Use Stream.map/filter for lazy, memory-efficient pipeline processing | | Global mutable state via Process dictionary | Process dictionary is implicit state; makes code unpredictable and untestable | Use Agent, GenServer, or ETS explicitly when shared state is required | | No doctests for public functions | Public API has no runnable specification; behavior drifts from documentation | Always add iex> examples in @doc; run with mix test

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: largelanguageplatform
• Source: largelanguageplatform/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.