Installation
While Phoenix LiveView is under heavy development, the installation instructions are likely to change rapidly as well. The instructions below will serve if you are installing the latest stable version from Hex. If you are installing from GitHub to get the latest features, follow the instructions in the README there instead.
To start using LiveView, add to your mix.exs
and run mix deps.get
. If
installing from Hex, use the latest version from there:
def deps do
[
{:phoenix_live_view, "~> 0.4.1"},
{:floki, ">= 0.0.0", only: :test}
]
end
If you want the latest features, install from GitHub:
def deps do
[
{:phoenix_live_view, github: "phoenixframework/phoenix_live_view"},
{:floki, ">= 0.0.0", only: :test}
]
Once installed, update your endpoint's configuration to include a signing salt.
You can generate a signing salt by running mix phx.gen.secret 32
.
# config/config.exs
config :my_app, MyAppWeb.Endpoint,
live_view: [
signing_salt: "SECRET_SALT"
]
Next, add the LiveView flash plug to your browser pipeline, after :fetch_flash
:
# lib/my_app_web/router.ex
pipeline :browser do
...
plug :fetch_flash
plug Phoenix.LiveView.Flash
end
Then add the following imports to your web file in lib/my_app_web.ex
:
# lib/my_app_web.ex
def controller do
quote do
...
import Phoenix.LiveView.Controller
end
end
def view do
quote do
...
import Phoenix.LiveView.Helpers
end
end
def router do
quote do
...
import Phoenix.LiveView.Router
end
end
Next, expose a new socket for LiveView updates in your app's endpoint module.
# lib/my_app_web/endpoint.ex
defmodule MyAppWeb.Endpoint do
use Phoenix.Endpoint
socket "/live", Phoenix.LiveView.Socket,
websocket: [connect_info: [session: @session_options]]
# ...
end
Where @session_options
are the options given to plug Plug.Session
extracted to a module attribute.
Add LiveView NPM dependencies in your assets/package.json
. For a regular project, do:
{
"dependencies": {
"phoenix": "file:../deps/phoenix",
"phoenix_html": "file:../deps/phoenix_html",
"phoenix_live_view": "file:../deps/phoenix_live_view"
}
}
However, if you're adding phoenix_live_view
to an umbrella project, the dependency paths should be modified appropriately:
{
"dependencies": {
"phoenix": "file:../../../deps/phoenix",
"phoenix_html": "file:../../../deps/phoenix_html",
"phoenix_live_view": "file:../../../deps/phoenix_live_view"
}
}
Then install the new npm dependency.
npm install --prefix assets
# or `cd assets && npm install` for Windows users if --prefix doesn't work
If you had previously installed phoenix_live_view
and want to get the
latest javascript, then force an install.
(cd assets && npm install --force phoenix_live_view)
Ensure you have placed a CSRF meta tag inside the <head>
tag in your layout (lib/my_app_web/templates/layout/app.html.eex
) like so:
<%= csrf_meta_tag() %>
Enable connecting to a LiveView socket in your app.js
file.
// assets/js/app.js
import {Socket} from "phoenix"
import LiveSocket from "phoenix_live_view"
let csrfToken = document.querySelector("meta[name='csrf-token']").getAttribute("content");
let liveSocket = new LiveSocket("/live", Socket, {params: {_csrf_token: csrfToken}});
liveSocket.connect()
You can also optionally import the style for the default CSS classes in your app.css
file. For a regular project:
/* assets/css/app.css */
@import "../../deps/phoenix_live_view/assets/css/live_view.css";
However, if you're adding phoenix_live_view
to an umbrella project, the import link should be modified appropriately:
/* assets/css/app.css */
@import "../../../../deps/phoenix_live_view/assets/css/live_view.css";