Filament Peek Laravel Package

Getting Started

capell-app/filament-peek is a fork of pboivin/filament-peek — a Filament plugin that adds a Preview button to resource pages so editors can see a record's front-end page (or their unsaved form state) in a modal before publishing. The 1.0.x line is the "stable, no surprises" branch; v1.0.49 is a patch release, so nothing in your setup should need to change.

Minimal setup:

1. composer require capell-app/filament-peek
2. Publish the config: php artisan vendor:publish --tag=filament-peek-config (add --tag=filament-peek-views only if you intend to restyle the modal).
3. Open config/filament-peek.php first — it's the whole surface area of the package: modal sizing, internal page patterns, front-end asset/theme handling.
4. On the resource that backs your public content (a Page, Post, LandingPage model), implement the package's preview contract and return the public URL for a record. This is the one piece of glue code you own.
5. Add the preview action to the edit page header:

protected function getHeaderActions(): array
{
    return [
        PreviewAction::make(),
    ];
}

First use case to validate end-to-end: open a draft record, hit Preview, and confirm the iframe renders the front-end page for an unpublished record. That single flow exercises the URL resolution, the auth/session handoff, and the iframe headers — the three things that break.

Implementation Patterns

Put URL resolution on the model, not the resource. Resources get copied, renamed and split; a previewUrl() method (or a small PreviewUrlResolver) on the model keeps getPreviewUrl() a one-liner and gives you somewhere sane to add locale/tenant/domain logic.

Unsaved-changes preview is the real feature. Peek serialises the current Livewire form state and renders the front-end view with it, so editors see typography and layout changes without saving. Use it for content types where the visual result matters (marketing pages, block builders, long-form articles). For structured data where the front-end barely changes (a category, a settings row), the plain record preview is enough — don't add buttons that show the same page every time.

Side-by-side editing (preview stays open while the form stays editable) is the workflow pattern worth adopting for a CMS: editors tweak copy in the left pane, watch the iframe on the right, save once. It pairs badly with heavy modals-in-modals, so keep the resource form flat.

Table-row previews for read-only triage: put the action in ->actions([...]) so reviewers can eyeball a record without entering the edit page and risking an accidental save.

Multi-panel / multi-guard apps: register the plugin per panel and make sure your admin path is listed under the internal page patterns in config, otherwise the package will happily try to iframe your own admin screens.

Test it like a route. A feature test that hits the preview URL for a draft record and asserts 200 + a fragment of expected content catches 90% of regressions (guard changes, middleware changes, policy changes) before an editor does.

Gotchas and Tips

• X-Frame-Options / CSP frame-ancestors is the #1 cause of a blank modal. Laravel sends SAMEORIGIN by default; if the front-end lives on a different subdomain or port than the admin, the iframe is silently refused. Check the browser console first, not your logs.
• Cross-domain sessions. Preview requests run inside the iframe with the browser's cookies. Admin on admin.example.com and front-end on www.example.com means SameSite=Lax session cookies may not be sent, and you get a redirect to the login page rendered inside the modal. Fix at the cookie/domain config level, or proxy through a preview route on the front-end domain.
• Create pages have no record. Guard getPreviewUrl() against a null record and return a sensible placeholder route, or hide the action until the form has been saved once.
• Unsaved preview only sees Livewire-bound state. Anything manipulated in JS outside the component (a hand-rolled rich-text editor, a map widget, client-side reordering that never dispatches to Livewire) will be stale in the preview. File uploads are the classic case: temporary uploads live in Livewire's temp disk and may not resolve from your front-end view — either resolve the temp path explicitly or accept that images only appear after save.
• Front-end assets inside the iframe. If your public layout pulls its own CSS/JS, you can end up double-loading or fighting the package's asset handling. Use the config flags to disable asset loading when your layout is self-sufficient, and keep the preview theme aligned with production so what editors approve is what ships.
• Caching kills the feature quietly. If the front-end route is behind a response cache or a CDN, an editor previews stale HTML and files a bug against the plugin. Mark preview responses no-store.
• 419s are easy to misread. A CSRF failure inside the modal looks like a broken preview; confirm the request actually reached your app in storage/logs/laravel.log before touching config.
• Extension points: publish the views to override the modal markup, use the action's modal helpers for heading/width without touching the package, and keep the config file in version control with only the keys you actually change — future patch bumps are then trivial to diff.
• On v1.0.49 specifically: the release note is only a compare link against v1.0.45, with no documented breaking changes, new features, or deprecations. Treat it as a safe patch bump. Before deploying, diff the composer.json Filament constraint in the tag (forks commonly widen Filament major support inside patch releases) and re-run your preview smoke test on draft, published, and create-page flows.