English for Phoenix LiveView Developers

Phoenix LiveView’s model — stateful server processes pushing DOM diffs over a persistent socket — doesn’t map cleanly onto the SPA vocabulary most developers already know, so explaining a LiveView bug precisely requires its own terms. This guide covers them.

Key Vocabulary

Socket — the persistent WebSocket connection between the client and a LiveView process, carrying events up and DOM diffs down for the lifetime of the page. “The disconnected state you’re seeing means the socket dropped — check whether it’s a network blip or the LiveView process itself crashed on the server.”

Assigns — the state stored on a LiveView’s socket (accessed via socket.assigns), analogous to component state, updated with assign/3 and re-rendered whenever changed. “The count isn’t updating in the template because we mutated a local variable instead of calling assign — LiveView only re-renders when assigns actually change.”

Diff (DOM patch) — the minimal set of changes LiveView computes and sends to the client after a state update, rather than re-sending the full rendered HTML each time. “LiveView doesn’t resend the whole page on every event — it computes a diff of just the changed parts and patches the existing DOM.”

handle_event — the callback that receives client-triggered events (button clicks, form submissions) sent over the socket and returns an updated socket with new assigns. “The button isn’t doing anything because the phx-click attribute doesn’t match any clause in handle_event — check the event name string matches exactly.”

LiveView process — the stateful Erlang/Elixir process on the server that holds a specific LiveView’s assigns for the duration of a connection, one per connected client. “Each connected user gets their own LiveView process, so state isn’t shared between tabs the way a global server variable would be.”

Hook (JS hook) — a small piece of client-side JavaScript attached to a DOM element via phx-hook, used for behavior LiveView’s server-driven model can’t handle alone, like a chart library or clipboard access. “We added a JS hook for the chart component since rendering a canvas element is something the client has to do — LiveView can’t push canvas drawing instructions as a diff.”

Common Phrases

• “Is the socket actually connected, or is this a ‘disconnected’ state issue?”
• “Did we call assign here, or are we mutating the assigns map directly and expecting a re-render that won’t happen?”
• “Is this event even reaching handle_event, or is the phx-click binding wrong?”
• “Is this per-user state living correctly in the LiveView process, or did we accidentally make it global?”
• “Does this need a JS hook, or can LiveView handle it with a plain diff?”

Example Sentences

Explaining a bug in a PR description: “The counter wasn’t updating because the increment logic mutated the assigns map in place instead of calling assign/3 — LiveView tracks changes by reference, so a mutation in place doesn’t trigger a re-render.”

Reporting a socket issue: “Users on flaky connections are seeing a stuck ‘reconnecting’ banner — it looks like the LiveView process is crashing on reconnect rather than resuming cleanly, based on the error logs.”

Discussing an architecture decision: “We’re adding a JS hook for the drag-and-drop interaction rather than trying to model it entirely server-side — some interactions are genuinely client-local and don’t need a round trip.”

Professional Tips

• Say assigns, not “state,” when the context is specifically LiveView — it’s the term reviewers expect and ties directly to assign/3 semantics that plain “state” doesn’t convey.
• Reference the socket connection state explicitly when debugging UI that stops responding — “the page is frozen” is much less actionable than “the socket disconnected.”
• Clarify whether logic lives in the LiveView process or a JS hook when discussing where a feature should be implemented — it’s the central architectural decision in most LiveView PRs.
• Use diff or DOM patch when discussing performance, since LiveView’s efficiency comes specifically from sending only changed markup, not full page re-renders.

Practice Exercise

1. Explain in one sentence why mutating assigns directly doesn’t trigger a re-render.
2. Write a bug report describing a socket that disconnects and doesn’t recover.
3. Describe, in your own words, when a JS hook is needed versus plain LiveView.