PhoenixReplay needs Elixir 1.18 or later and Phoenix LiveView 1.1 or later.
Install with Igniter
mix igniter.install phoenix_replay
The installer imports PhoenixReplay's formatter settings, mounts the dashboard at /dev/replay behind your :dev_routes flag (like Phoenix's LiveDashboard), turns recording off in config/test.exs, and ignores the local recordings directory. It also sends browser context to recordings: it adds :user_agent to your LiveView socket's connect_info, passes PhoenixReplay's client helpers to LiveSocket and starts replayRecorder in assets/js/app.js when that file still has the setup Phoenix generates, and adds PhoenixReplay.Plug to your :browser pipeline for visit context. It then prints how to record a live session, which is the step below.
Install manually
Add the dependency:
def deps do
[{:phoenix_replay, "~> 0.6"}]
endAdd :phoenix_replay to import_deps in .formatter.exs, so mix format leaves the router macro without parentheses:
[
import_deps: [:ecto, :phoenix, :phoenix_replay],
# ...
]Turn recording off in config/test.exs; see Testing.
Optionally, send the browser's viewport, user agent and tab with recordings, as Browser and journey describes, and start replayRecorder to record form input and, with pointer: true, the pointer; see Client state.
Record a live session
Add PhoenixReplay.Recorder to the on_mount hooks of the live sessions you want to record:
live_session :default, on_mount: [PhoenixReplay.Recorder] do
live "/", HomeLive
live "/checkout", CheckoutLive
endEvery connected LiveView in the session is now recorded, including its LiveComponents. Nothing changes in your views or components, and the JavaScript side is optional.
Mount the dashboard
Import the router macro and mount the dashboard behind your own authentication:
defmodule MyAppWeb.Router do
use MyAppWeb, :router
import PhoenixReplay.Router
scope "/admin" do
pipe_through [:browser, :require_admin]
phoenix_replay "/replay"
end
endRecordings can contain business data, so never mount the dashboard on a public route. See Privacy and Security.
Watch a replay
Start your app, use a recorded page for a while, then navigate away or close the tab. Open /admin/replay: the session is listed with its view, page, device, start time, duration, event count and errors. Click its row to replay it.
The player re-renders your view inside an iframe with the assigns recorded at each event. Move through it with the timeline, the event list, or the keyboard: ← and → step, Space plays or pauses, and ? lists the other shortcuts. The State tab shows the assigns at each moment, and Copy link shares the moment you are looking at.
Testing
Your LiveView tests mount connected views, so with the recorder in your live sessions they would record sessions and save them to storage during every test run. Turn recording off in config/test.exs:
config :phoenix_replay, sample_rate: 0.0To test a flow with recording on, give its live session its own rate. Per-session options override the global configuration:
live_session :checkout, on_mount: [{PhoenixReplay.Recorder, sample_rate: 1.0}] do
live "/checkout", CheckoutLive
endand point :storage at a temporary directory in config/test.exs. Sanitizers and authorization modules are plain modules, so test them by calling their callbacks directly.
Next steps
- Recording — what is recorded, sampling and limits
- Dashboard — authorization, filters and the replay frame
- Telemetry and Logs — queries, requests, logs and marks
- Privacy and Security — sanitizing and redaction
- Storage — files, Ecto and retention
- Configuration cheatsheet