Filament Truss Laravel Package

Getting Started

This is a Filament panel plugin that renders the Truss responsive diagram inside the admin panel, so the first thing to understand is that it is a viewer, not a page builder: you are looking at Truss output from within Filament rather than authoring layouts there.

1. composer require albertoarena/filament-truss — the release notes pin the floor at albertoarena/laravel-truss 1.13.1+, so check your lock resolves at or above that before you start debugging anything visual.
2. Register the plugin on the panel you actually use (typically AdminPanelProvider), not globally — the diagram is a panel-scoped concern and registering it everywhere just adds surface area to every panel you maintain.
3. Confirm the environment matrix up front: PHP 8.2+, Laravel 12+, Filament 5. On an older Filament this will not install, and the failure surfaces at composer time rather than runtime, which is at least honest.
4. Look first at the package documentation and then at the panel provider registration — the docs are the canonical source for the plugin's configuration surface, and the provider is where anything you get wrong will be wrong.

First use case: open the panel at a realistic viewport with your production sidebar present, and check the toolbar renders correctly. The whole point of v1.0.1 is that a panel at a 1280px window leaves roughly 810px of toolbar once the sidebar is subtracted, so testing at full window width in isolation tells you nothing.

Implementation Patterns

Treat the dependency floor as part of your install, not part of your upgrade. The pragmatic pattern is to require albertoarena/laravel-truss explicitly at ^1.13.1 in your own composer.json rather than relying on this package's transitive constraint to pull it in. That way the Truss version is visible in your diff, reviewed like any other dependency, and not silently resolved to whatever the host happened to have cached. The release notes make this point directly: if your lock already holds 1.13.1 you already have the fix, and if it doesn't, upgrading this package alone may leave you on the broken Truss.

Register per-panel, and be deliberate about which panels get it. Local and staging panels are the natural home; production panels are a judgement call. If the diagram is genuinely useful to content editors, register it there; if it is a development aid, gate it on environment so you are not shipping a debugging affordance to end users.

Verify in the shape your users actually see. The bug fixed here only reproduced inside a panel with a sidebar, at a window width where the toolbar's responsive steps had room to fire against the window but not against the bar. Build a small habit of checking toolbar behaviour at two or three widths with the sidebar open — that is the configuration the responsive logic has to survive, and it is the configuration that a browser-window-only test misses.

Keep upgrades boring. Because this package's markup, styles and script did not change in v1.0.1, an upgrade is a composer resolution and a cache clear, nothing more. That is worth knowing explicitly: it means you can take patch releases here on a routine schedule without budgeting visual regression review, and save the careful review for releases that do touch the front end.

Gotchas and Tips

The failure mode is a collapsed control, not an error. The Filter field shrinking to an empty square produced no exception, no console warning, no failing test — just a control that looked wrong in exactly one layout context. When something in this toolbar looks subtly off, reach for the browser inspector and measure the toolbar's actual width before you theorise; the bug here was that Truss sized its steps from the window instead of the bar, and the whole shortfall landed on the one control not floored at its content width.

Pin Truss, don't inherit it. The single most likely way to hit the old bug after upgrading is to upgrade this package while a stale or independently-constrained laravel-truss stays at 1.13.0. Run composer show albertoarena/laravel-truss after upgrading and read the version rather than assuming the upgrade carried the fix.

Filament 5 and Laravel 12 are hard floors. There is no graceful degradation path here; the plugin will not install on Filament 4. If you are mid-migration on a panel, this package waits until that panel is on 5, which is fine but worth scheduling rather than discovering.

Asset and view caches bite after any dependency change. Because nothing in this package's own assets changed, a broken render after upgrading points at Truss, not at the plugin — but clear compiled views and any published assets anyway before you start bisecting, since a stale cache mimics a version problem convincingly.

Extension points are thin by design. This package puts a diagram in a panel and delegates the responsive work to Truss. When you want different toolbar behaviour, the lever is Truss configuration, not this plugin's config; going upstream is the supported direction, and v1.0.1 is a clean illustration of the maintainer treating it that way rather than patching around the dependency locally.