Help us improve
Share bugs, ideas, or general feedback.
From all-skills
Guides Phoenix web app development including LiveView, contexts, channels, and production runtime configuration.
npx claudepluginhub vinnie357/claude-skills --plugin qaHow this skill is triggered — by the user, by Claude, or both
Slash command
/all-skills:phoenixThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill activates when working with Phoenix web applications, including setup, development, LiveView, contexts, controllers, and channels.
Guides Phoenix web app development in Elixir: LiveView lifecycle and components, context design and generation, channels, routers, plugs, project structure, and troubleshooting.
Provides examples, walkthroughs, official guides, and plugin-specific patterns for Phoenix, LiveView, Ecto, and OTP. Use for 'how do I...', 'show me an example', or 'what does X look like' queries.
Implements Phoenix Framework patterns for context design, controller actions, fallback handling, and plug pipelines when building Elixir web applications.
Share bugs, ideas, or general feedback.
This skill activates when working with Phoenix web applications, including setup, development, LiveView, contexts, controllers, and channels.
Current versions: Phoenix 1.8.x (current: 1.8.5), Phoenix LiveView 1.1.x (current: 1.1.27). Requires Elixir 1.14+, Erlang/OTP 25+.
Activate this skill when:
Follow Phoenix conventions:
lib/
my_app/ # Business logic and contexts
accounts/ # Domain contexts
repo.ex
my_app_web/ # Web interface
controllers/
live/ # LiveView modules
components/ # Function components
router.ex
endpoint.ex
config/runtime.exs runs at every boot (dev, test, prod). Three settings have caused production outages when configured incorrectly:
:ip bind configThe Endpoint's :ip bind tuple MUST be set at the TOP LEVEL of runtime.exs, env-driven, with a default of {0, 0, 0, 0} (all IPv4 interfaces). Do NOT gate it inside if port = System.get_env("PORT") do ... end, and do NOT override it later in a prod-only block that hardcodes {0,0,0,0,0,0,0,0} (IPv6 wildcard).
CORRECT:
# config/runtime.exs (top level, unconditional)
bind_address =
case System.get_env("BIND_ADDRESS", "0.0.0.0") do
"0.0.0.0" -> {0, 0, 0, 0}
"::" -> {0, 0, 0, 0, 0, 0, 0, 0}
other -> other |> String.to_charlist() |> :inet.parse_address() |> elem(1)
end
config :<app>, <App>Web.Endpoint, http: [ip: bind_address, port: ...]
WRONG (gates on PORT):
if port = System.get_env("PORT") do
config :<app>, <App>Web.Endpoint, http: [ip: {0, 0, 0, 0}, port: ...]
end
# Without PORT, Phoenix falls back to its default 127.0.0.1 — unreachable.
WRONG (later prod block clobbers env-driven setting):
# Top-level env-driven config OK ...
if config_env() == :prod do
config :<app>, <App>Web.Endpoint, http: [ip: {0, 0, 0, 0, 0, 0, 0, 0}, ...]
end
# IPv6 wildcard binds *:port IPv6 only — IPv4-only overlay networks (Tailscale on macOS) cannot reach it.
Default to IPv4 because most overlay networks route IPv4 first on macOS. Add IPv6 only when the deployment target explicitly requires it.
Set PHX_HOST to the externally-resolvable hostname the load balancer presents to the browser. LiveView's websocket upgrade matches Origin against PHX_HOST; a mismatch causes the LiveView socket to fail with 403 and the page reverts to a dead static render.
lib/**/*.ex changesPhoenix live reload covers .heex / .html.eex templates and assets/ reliably. It does NOT reliably pick up changes to:
lib/**/*.ex — compiled Elixir modulesmix.exs or any dependency changeconfig/*.exs, especially runtime.exsAfter any of those changes, restart the dev server (kill + relaunch the mise run dev session or equivalent). /api/info-style endpoints report the git_sha at server-start time, NOT the currently-compiled-in-memory code, and cannot distinguish stale-dev from fresh-dev. Restart is the only reliable signal.
Organize business logic into contexts (bounded domains):
Generate contexts with related schemas:
mix phx.gen.context Accounts User users email:string name:string
Structure contexts to encapsulate business logic:
defmodule MyApp.Accounts do
@moduledoc """
The Accounts context - manages user accounts and authentication.
"""
alias MyApp.Repo
alias MyApp.Accounts.User
def list_users do
Repo.all(User)
end
def get_user!(id), do: Repo.get!(User, id)
def create_user(attrs \\ %{}) do
%User{}
|> User.changeset(attrs)
|> Repo.insert()
end
def update_user(%User{} = user, attrs) do
user
|> User.changeset(attrs)
|> Repo.update()
end
end
LiveView enables rich, real-time experiences without writing JavaScript.
Understand the mount → handle_event → render cycle:
defmodule MyAppWeb.UserLive.Index do
use MyAppWeb, :live_view
alias MyApp.Accounts
@impl true
def mount(_params, _session, socket) do
# Runs on initial page load and live connection
{:ok, assign(socket, :users, list_users())}
end
@impl true
def handle_params(params, _url, socket) do
# Runs after mount and on live patch
{:noreply, apply_action(socket, socket.assigns.live_action, params)}
end
@impl true
def handle_event("delete", %{"id" => id}, socket) do
user = Accounts.get_user!(id)
{:ok, _} = Accounts.delete_user(user)
{:noreply, assign(socket, :users, list_users())}
end
@impl true
def render(assigns) do
~H"""
<div>
<.table rows={@users} id="users">
<:col :let={user} label="Name"><%= user.name %></:col>
<:col :let={user} label="Email"><%= user.email %></:col>
<:action :let={user}>
<.button phx-click="delete" phx-value-id={user.id}>Delete</.button>
</:action>
</.table>
</div>
"""
end
defp list_users do
Accounts.list_users()
end
end
mount/3 for initial data loadinghandle_params/3assign_new/3 for expensive computationsphx-debounce and phx-throttle for frequent eventsCreate reusable components:
defmodule MyAppWeb.Components.UserCard do
use Phoenix.Component
attr :user, :map, required: true
attr :class, :string, default: ""
def user_card(assigns) do
~H"""
<div class={"card " <> @class}>
<h3><%= @user.name %></h3>
<p><%= @user.email %></p>
</div>
"""
end
end
Use with <.user_card user={@current_user} /> in templates.
Use changesets for validation:
@impl true
def mount(_params, _session, socket) do
changeset = Accounts.change_user(%User{})
{:ok, assign(socket, form: to_form(changeset))}
end
@impl true
def handle_event("validate", %{"user" => user_params}, socket) do
changeset =
%User{}
|> Accounts.change_user(user_params)
|> Map.put(:action, :validate)
{:noreply, assign(socket, form: to_form(changeset))}
end
@impl true
def handle_event("save", %{"user" => user_params}, socket) do
case Accounts.create_user(user_params) do
{:ok, user} ->
{:noreply,
socket
|> put_flash(:info, "User created successfully")
|> push_navigate(to: ~p"/users/#{user}")}
{:error, %Ecto.Changeset{} = changeset} ->
{:noreply, assign(socket, form: to_form(changeset))}
end
end
def render(assigns) do
~H"""
<.form for={@form} phx-change="validate" phx-submit="save">
<.input field={@form[:name]} label="Name" />
<.input field={@form[:email]} label="Email" type="email" />
<.button>Save</.button>
</.form>
"""
end
Structure routes logically:
defmodule MyAppWeb.Router do
use MyAppWeb, :router
pipeline :browser do
plug :accepts, ["html"]
plug :fetch_session
plug :fetch_live_flash
plug :put_root_layout, html: {MyAppWeb.Layouts, :root}
plug :protect_from_forgery
plug :put_secure_browser_headers
end
pipeline :api do
plug :accepts, ["json"]
end
scope "/", MyAppWeb do
pipe_through :browser
live "/", HomeLive, :index
live "/users", UserLive.Index, :index
live "/users/new", UserLive.Index, :new
live "/users/:id", UserLive.Show, :show
end
scope "/api", MyAppWeb do
pipe_through :api
resources "/users", UserController, except: [:new, :edit]
end
end
Use live actions for modal/overlay states:
live "/users", UserLive.Index, :index
live "/users/new", UserLive.Index, :new
live "/users/:id/edit", UserLive.Index, :edit
Then handle in handle_params/3:
defp apply_action(socket, :edit, %{"id" => id}) do
socket
|> assign(:page_title, "Edit User")
|> assign(:user, Accounts.get_user!(id))
end
defp apply_action(socket, :new, _params) do
socket
|> assign(:page_title, "New User")
|> assign(:user, %User{})
end
defp apply_action(socket, :index, _params) do
socket
|> assign(:page_title, "Listing Users")
|> assign(:user, nil)
end
For custom real-time protocols:
defmodule MyAppWeb.RoomChannel do
use MyAppWeb, :channel
@impl true
def join("room:" <> room_id, _payload, socket) do
if authorized?(socket, room_id) do
{:ok, assign(socket, :room_id, room_id)}
else
{:error, %{reason: "unauthorized"}}
end
end
@impl true
def handle_in("new_msg", %{"body" => body}, socket) do
broadcast!(socket, "new_msg", %{body: body, user: socket.assigns.user})
{:noreply, socket}
end
end
For LiveView updates and process communication:
# Subscribe in mount
def mount(_params, _session, socket) do
if connected?(socket) do
Phoenix.PubSub.subscribe(MyApp.PubSub, "users")
end
{:ok, assign(socket, :users, list_users())}
end
# Handle broadcasts
def handle_info({:user_created, user}, socket) do
{:noreply, update(socket, :users, fn users -> [user | users] end)}
end
# Broadcast from context
def create_user(attrs) do
with {:ok, user} <- do_create_user(attrs) do
Phoenix.PubSub.broadcast(MyApp.PubSub, "users", {:user_created, user})
{:ok, user}
end
end
defmodule MyAppWeb.UserControllerTest do
use MyAppWeb.ConnCase, async: true
test "GET /users", %{conn: conn} do
conn = get(conn, ~p"/users")
assert html_response(conn, 200) =~ "Listing Users"
end
end
defmodule MyAppWeb.UserLiveTest do
use MyAppWeb.ConnCase
import Phoenix.LiveViewTest
test "displays users", %{conn: conn} do
user = insert(:user)
{:ok, view, html} = live(conn, ~p"/users")
assert html =~ user.name
assert has_element?(view, "#user-#{user.id}")
end
test "creates user", %{conn: conn} do
{:ok, view, _html} = live(conn, ~p"/users/new")
assert view
|> form("#user-form", user: %{name: "Alice", email: "alice@example.com"})
|> render_submit()
assert_patch(view, ~p"/users")
end
end
defmodule MyAppWeb.RoomChannelTest do
use MyAppWeb.ChannelCase
test "broadcasts are pushed to the client", %{socket: socket} do
{:ok, _, socket} = subscribe_and_join(socket, "room:lobby", %{})
broadcast_from!(socket, "new_msg", %{body: "test"})
assert_broadcast "new_msg", %{body: "test"}
end
end
Preload associations efficiently:
def list_posts do
Post
|> preload([:author, comments: :author])
|> Repo.all()
end
Use Scrivener or custom pagination:
def list_users(page \\ 1) do
User
|> order_by(desc: :inserted_at)
|> Repo.paginate(page: page, page_size: 20)
end
Handle uploads in LiveView:
def mount(_params, _session, socket) do
{:ok,
socket
|> assign(:uploaded_files, [])
|> allow_upload(:avatar, accept: ~w(.jpg .jpeg .png), max_entries: 1)}
end
def handle_event("save", _params, socket) do
uploaded_files =
consume_uploaded_entries(socket, :avatar, fn %{path: path}, _entry ->
dest = Path.join("priv/static/uploads", Path.basename(path))
File.cp!(path, dest)
{:ok, "/uploads/" <> Path.basename(dest)}
end)
{:noreply, update(socket, :uploaded_files, &(&1 ++ uploaded_files))}
end
preload/2 to avoid N+1 queriesselect/3 to load only needed fieldsRepo.stream/2 for large datasetshandle_event or background jobsassign_new/3 for computed valueshandle_continue/2 for async operations after mountassign(socket, :items, temporary: true)Use Cachex or ETS for caching:
def get_user!(id) do
Cachex.fetch(:users, id, fn ->
{:commit, Repo.get!(User, id)}
end)
end
put_secure_browser_headers plugDefine the OpenAPI spec for any HTTP API surface BEFORE implementing the controller. Clients (and Tier 2 test authors) generate from the spec; the implementation makes the spec true.
In Elixir, use open_api_spex for spec definitions:
defmodule <App>Web.UserSpec do
alias OpenApiSpex.{Schema, Operation}
@user_schema %Schema{
type: :object,
required: [:id, :email],
properties: %{
id: %Schema{type: :integer},
email: %Schema{type: :string, format: :email}
}
}
end
Wire the spec to the controller via @spec macros and serve it at /api/openapi. Tests assert response shapes against the spec rather than against hand-rolled JSON expectations; client SDKs regenerate from the spec on every spec change.
Tidewave connects AI coding assistants to running Phoenix applications via MCP, exposing runtime introspection tools (Ecto schemas, code execution, docs, logs, SQL queries).
Add to mix.exs: {:tidewave, "~> 0.5", only: :dev}
Add to endpoint.ex before code_reloading?: plug Tidewave (guarded by if Mix.env() == :dev)
Connect Claude Code: claude mcp add --transport http tidewave http://localhost:4000/tidewave/mcp
Tidewave is dev-only — never deploy to production. It only accepts localhost requests by default.
For full setup, MCP tools reference, CLI app, editor configs, LiveView annotations, and troubleshooting, load the tidewave skill or see references/tidewave.md.