Build libraries that mount into a Phoenix app.

A mountable library brings its own routes, LiveViews, controllers, assets and processes, and a host app mounts it with one line in its router:

# in the host router
import MyLib.Router

scope "/" do
  pipe_through :browser
  my_lib "/my_lib", resolver: MyApp.MyLibResolver
end

The library declares everything in a definition module:

defmodule MyLib.Router do
  use PhoenixMountable,
    otp_app: :my_lib,
    macro: :my_lib,
    layout: {MyLib.Layouts, :root},
    assets:
      {PhoenixMountable.Assets.Embedded,
       css: "priv/static/app.css",
       js: "priv/static/app.js",
       prepend: [:phoenix, :phoenix_html, :phoenix_live_view, :phoenix_mountable]}

  options resolver: [type: :atom, default: MyLib.Resolver, verify: {:behaviour, MyLib.Resolver}],
          features: [type: {:list, :atom}, default: []]

  routes do
    get "/export", MyLib.ExportController, :csv

    live_session :public, host_on_mount: false do
      live "/share/:token", MyLib.ShareLive, :show
    end

    live_session :default, on_mount: [MyLib.Auth] do
      live "/", MyLib.HomeLive, :index
      live "/items/:id", MyLib.ItemLive, :show
    end
  end
end

The generated macro (my_lib/2) inserts ordinary Phoenix routes and live sessions into the host router: mix phx.routes lists them, the host's pipelines and scopes apply to them, and LiveView navigation works between them. LiveView is optional: a library of controllers and plugs mounts in a host without it.

See PhoenixMountable.Definition for options/1, routes/1 and pipeline/2, and PhoenixMountable.Routes for the routes.

use options

• :otp_app (atom/0) - Required. The library's OTP application.

• :macro (atom/0) - Required. The name of the mount macro defined for hosts.

• :as (atom/0) - The default mount name, used to name live sessions and route helpers. Defaults to the macro name. Hosts pass :as to mount the library more than once.

• :title (String.t/0) - The page title of PhoenixMountable.Layout. Defaults to the camelized OTP application.

• :layout - The root layout of the library's pages: a {module, function} tuple for a document of its own (such as {PhoenixMountable.Layout, :root}), or :host to render inside the host's root layout. The default value is :host.

• :assets - How the library's CSS and JavaScript reach the browser: {strategy, options}. See PhoenixMountable.Assets. The default value is nil.

• :on_mount - on_mount hooks of the library, run in every library live session after the host's. The default value is [].

• :schema (atom/0) - The library's PhoenixMountable.Migrations module. The first use of each mount then checks the host has run the library's migrations; see PhoenixMountable.repo/1.

• :reload_on_stale (boolean/0) - Reload a page whose library assets belong to a previous build when its LiveView reconnects. The default value is true.

• :socket_path (String.t/0) - The default of the :socket_path mount option. The default value is "/live".

• :transport - The default of the :transport mount option. The default value is :websocket.

Mount options

Besides the options a library declares, every mount macro takes:

• :as (atom/0) - The mount name: names the live sessions and route helpers. Mount a library twice with different names.

• :on_mount - The host's on_mount hooks, run before the library's. The default value is [].

• :socket_path (String.t/0) - The path of the host's LiveView socket. Defaults to "/live".

• :transport - The LiveView transport, :websocket (default) or :longpoll.

• :csp_nonce_assign_key - The assign holding the request's CSP nonce, or a map of kinds to assigns, such as %{script: :script_nonce, style: :style_nonce}. The default value is nil.

• :asset_host - A scheme and host to load the library's assets from, such as a CDN. The default value is nil.

• :pubsub - The PubSub server of PhoenixMountable.PubSub. Defaults to the endpoint's. The default value is nil.

The mount

Library code reads the current PhoenixMountable.Mount as @mount in LiveViews and templates, conn.assigns.mount in controllers and plugs, or with PhoenixMountable.Mount.current/0 in the process handling them.