Split a Phoenix LiveView into smaller, composable modules.

Parent modules

A parent module declares its submodules with delegate/2:

defmodule MyAppWeb.DashboardLive do
  use MyAppWeb, :live_view
  use LiveDelegate

  alias MyAppWeb.DashboardLive.Projects
  alias MyAppWeb.DashboardLive.Users

  # Mount order follows declaration order: Users, then Projects.
  delegate(:users, Users)
  delegate(:projects, Projects)

  # A single call to delegate_mount/3 mounts the submodules, 
  # calling Users.on_mount/3 then Projects.on_mount/3.
  def mount(params, session, socket) do
    {:ok, socket |> delegate_mount(params, session)}
  end
end

Mounting delegated submodules

delegate_mount/3 runs the on_mount/3 callback of each delegated submodule whose mount: option is enabled:

# In parent module:
def mount(params, session, socket) do
  {:ok, delegate_mount(socket, params, session)}
end

# In submodules:
def on_mount(params, session, socket) do
  ...
end

Delegated submodules are mounted in declaration order. Each submodule receives the same params and session, along with the socket returned by the preceding submodule.

Unlike Phoenix.LiveView.mount/3, a delegated submodule's on_mount/3 callback must return the updated socket directly, not an {:ok, socket} tuple.

Set mount: false when a delegated submodule has no on_mount/3 callback, or when you want to prevent its on_mount/3 callback from being called:

delegate(:notifications, Notifications, mount: false)

If mounting is disabled for every delegated submodule, delegate_mount/3 returns the original socket unchanged.

Submodules

A submodule declares where it belongs with path::

defmodule MyAppWeb.DashboardLive.Projects do
  use LiveDelegate, path: [:projects]

  def on_mount(_params, _session, socket) do
    socket |> delegate_assign(%{items: []})
  end

  def handle_event("add", _params, socket) do
    {:noreply, socket}
  end
end

The path namespaces its assigns, events, and DOM IDs:

delegate_assign(socket, value)
delegate_event("add")       # "projects:add"
delegate_dom_id("form")     # "projects-form"

Nested submodules

A module can be both a submodule and a parent:

defmodule MyAppWeb.DashboardLive.Projects do
  use LiveDelegate, path: [:projects]

  alias MyAppWeb.DashboardLive.Projects.Filters

  delegate(:filters, Filters)

  def on_mount(params, session, socket) do
    socket
    |> delegate_assign(%{items: []})
    |> delegate_mount(params, session)
  end
end

The nested module declares its complete path:

defmodule MyAppWeb.DashboardLive.Projects.Filters do
  use LiveDelegate, path: [:projects, :filters]

  def on_mount(_params, _session, socket) do
    socket |> delegate_assign(%{})
  end
end

Its helpers now use the nested namespace:

delegate_event("change")    # "projects:filters:change"
delegate_dom_id("panel")    # "projects-filters-panel"

Messages and options

Use info: to route process messages by their first tuple element:

delegate(:notifications, Notifications,
  events: false,
  info: [:notification_received],
  mount: false
)

For example, {:notification_received, notification} calls:

Notifications.handle_info(notification, socket)

Use mount: false, events: false, or info: false when a submodule does not need that responsibility.