Laravel Packages

Session Replay for Laravel: Self-Hosted Browser Recordings

Published
Session Replay for Laravel: Self-Hosted Browser Recordings image

Session Replay for Laravel is a package from Packstub, built by Ion Căliman, that records what a person does in the browser so you can watch it inside your own app. It captures the DOM with rrweb, stores the recordings on your own disk and database, and serves the player behind a gate you define.

Here's what the package gives you:

  • One Blade directive records a page, with no front-end build step
  • Timeline markers for JavaScript errors, failed Livewire and fetch requests, server exceptions, web vitals, and rage clicks
  • Error-only recording keeps the last minute in the browser and uploads it only when something fails
  • Replay links in your logs through Laravel's Context, so an error report points at the recording
  • Privacy defaults that mask every input, skip guests, and store no IP address
  • Self-hosted storage as gzip chunks on any Laravel disk, with an index in your database
  • A viewSessionReplay gate that guards the recording list, the player, and every file behind them
  • A Filament plugin that adds the recordings to a Filament v5 panel

How Recording Works

You add the recorder to a layout with the @sessionReplay directive, placed before the closing </body> tag:

    @sessionReplay
</body>

The directive renders a small config object and a deferred script. The script records the page with rrweb, one recording per browser tab, and continues it across page loads until the tab sits idle. Every few seconds it uploads a gzipped batch to your app.

When the page renders, the server signs the current user, the tenant, and any custom properties into a token with your app key. The recorder sends that token with each upload, so the ingest endpoint needs no session, cookie, or CSRF token. The token is signed, not encrypted, so keep secrets out of the properties.

The built-in viewer at /session-replay lists recordings, with filters for recordings that have errors or a reported problem:

By default, every input is masked, guests are not recorded, and no IP address is stored. Livewire's wire:snapshot component state is stripped before upload, and the prune command deletes recordings after 30 days.

Timeline Markers for Errors and Failed Requests

The recorder adds markers to the timeline so you can jump straight to errors and other events:

  • Uncaught JavaScript errors and console.error() calls
  • Failed Livewire requests, and same-origin fetch or XHR requests that return a 500 or higher
  • Exceptions Laravel reports during a recorded request
  • Page loads, wire:navigate swaps, and Inertia or Vue Router page changes
  • LCP, INP, and CLS web vitals
  • Rage clicks: three or more clicks on the same spot within 700 ms

Clicking a marker moves the player to that moment. A server error marker also shows the exception class, the request method and path, and a report ID:

You can add your own markers from the browser, or wire a "report a problem" button to upload the recording with a report marker:

SessionReplay.mark('Checkout started', { cart: 3 });

SessionReplay.send('Wrong total on the invoice');

Record Only When Something Goes Wrong

In on_error mode, the recorder keeps the last minute of events in browser memory and uploads nothing until a trigger fires:

// config/session-replay.php
'mode' => 'on_error',

'on_error' => [
    'buffer_seconds' => 60,
    'triggers' => ['error', 'request'],
    'ask' => false,
],

When a JavaScript error or failed request happens, the recorder uploads the buffered window and keeps recording for the rest of the tab's session. You get the minute before the failure and what happened after it. Set ask to true to ask the person before anything is sent.

Link Log Entries to the Replay

While a recording runs, a global middleware adds the recording's ID and viewer URL to Laravel's Context. Laravel includes Context in every log entry for that request:

[2026-09-18 10:57:12] production.ERROR: Undefined array key "total"
{"exception":"…"} {"session_replay":"0b1c6a0e-…","session_replay_url":"https://app.test/session-replay/0b1c6a0e-…"}

Error trackers that read Context, such as Flare, Sentry, and Nightwatch, receive the same keys. A session_replay_moment key opens the replay three seconds before the failing request. In the other direction, you can register a URL with SessionReplay::logUrlUsing() to add an Open in logs button next to a server error's report ID, pointing at a tool like Log Viewer.

Installation

The package requires PHP 8.3 and Laravel 12 or 13. Install it and run the installer:

composer require packstub/session-replay
php artisan session-replay:install

After adding the @sessionReplay directive to your layouts, define who can watch recordings in the SessionReplayServiceProvider the installer publishes. Outside the local environment, nobody can watch a recording until this gate exists:

use Illuminate\Support\Facades\Gate;
use Packstub\SessionReplay\Models\ReplaySession;

Gate::define('viewSessionReplay', function ($user, ?ReplaySession $session = null): bool {
    return $user->is_admin;
});

Then schedule the cleanup command in routes/console.php to delete old recordings:

use Illuminate\Support\Facades\Schedule;

Schedule::command('session-replay:prune')->daily();

For Filament panels, the companion packstub/filament-session-replay package adds a filterable recordings resource, the player, and a relation manager for your users. The author also publishes a demo app, a small Laravel shop with recordings to watch.

You can find the source and documentation on GitHub.

Paul Redmond photo

Staff writer at Laravel News. Full stack web developer and author.

Sponsored

serpapi logo
SerpApi

The Web Search API for Your LLM and AI Applications

Visit SerpApi

The latest

View all →
Laravel AI SDK 1.4 Lets Agents Recover From Tool Failures image

Laravel AI SDK 1.4 Lets Agents Recover From Tool Failures

Read article
Laravel Read Replicas: Check if a Replica Has Caught Up image

Laravel Read Replicas: Check if a Replica Has Caught Up

Read article
UUID Request Input and Migration Failure Events in Laravel 13.42 image

UUID Request Input and Migration Failure Events in Laravel 13.42

Read article
Replay Missed Laravel Scheduled Tasks With Schedule Catchup image

Replay Missed Laravel Scheduled Tasks With Schedule Catchup

Read article
Search Polymorphic Relations and Filament Tables With Laravel Searchable image

Search Polymorphic Relations and Filament Tables With Laravel Searchable

Read article
Laravel Rest Api 3.0: Typed Fields, Metrics, and OpenAPI Docs image

Laravel Rest Api 3.0: Typed Fields, Metrics, and OpenAPI Docs

Read article