phoenix-liveview-essentials

Phoenix LiveView Essentials

RULES — Follow these with no exceptions

1. Always add @impl true before every callback (mount, handle_event, handle_info, render)
2. Initialize assigns before they're accessed in render/1 — use mount/3 for static defaults, handle_params/3 for URL-dependent assigns (pagination, filters, sorting)
3. Check connected?(socket) before PubSub subscriptions, timers, or side effects
4. Use Map.get(assigns, :key, default) for optional assigns in helper functions
5. Return proper tuples — {:ok, socket} from mount, {:noreply, socket} from handle_event
6. Use with for error handling in event handlers — assign errors to socket, don't crash
7. auto_upload: true works with submit, but entries must be fully uploaded before you consume them — check entry.done? / rely on consume_uploaded_entries only after progress completes; default to manual uploads unless you need incremental upload UX
8. Check core_components.ex for existing components before creating custom ones
9. Never query the database directly from LiveViews — call context functions instead

---

Critical Concept: Two-Phase Rendering

LiveView renders happen in TWO phases:

1. Static/Disconnected Render - Initial HTTP request

   • No WebSocket connection
   • connected?(socket) returns false
   • Side effects (PubSub, timers) won't work

2. Connected Render - WebSocket established

   • Full live functionality active
   • connected?(socket) returns true
   • Events and live updates work

Common Bug: Accessing uninitialized assigns during static render crashes with KeyError.

Solution: Initialize assigns before render — use mount/3 for static defaults, handle_params/3 for URL-dependent state.

---

LiveView Lifecycle

Mount Callback

@impl true
def mount(_params, _session, socket) do
  # Initialize static defaults here; URL-dependent assigns go in handle_params
  socket =
    socket
    |> assign(:user, nil)
    |> assign(:loading, false)
    |> assign(:data, [])

  # Only subscribe when connected
  if connected?(socket) do
    Phoenix.PubSub.subscribe(MyApp.PubSub, "topic")
  end

  {:ok, socket}
end