Filament Breakpoint Badge Laravel Package

Getting Started

This is a small, single-purpose dev tool: it renders a badge showing the current Tailwind breakpoint inside a Filament panel, so you stop guessing whether you're at md, lg, or 2xl while building responsive admin UI.

Minimal path:

1. composer require chrisreedio/filament-breakpoint-badge — on Laravel 11 you need v3.0.1 or later, since v3.0.1 is the release that refreshed the dependency constraints for Laravel 11. Pin ^3.0.1 rather than ^3.0.0.
2. Register the plugin in the panel provider you actually develop against (app/Providers/Filament/AdminPanelProvider.php), in the ->plugins([...]) array.
3. Run php artisan filament:upgrade (and php artisan optimize:clear if you have config/route caching on) so the panel picks up the new plugin.
4. Load any panel page and resize the browser; the badge should tick over at your Tailwind breakpoints.

Where to look first: the package's src/ for the plugin class and any render-hook registration, then the README for the exact class name and any publishable config/views. It's a tiny package — you can read the whole source in a few minutes, which is the fastest way to know exactly which render hook it mounts to and whether it ships a config file.

First real use case: you're tuning a Filament resource table or a custom dashboard widget and need to know which breakpoint the columns are collapsing at. Keep the badge on in local, verify the layout, then gate it off so it never ships to production.

Implementation Patterns

Gate it to non-production environments. The single most important pattern. Register the plugin conditionally so it cannot appear in staging/production:

->plugins(array_filter([
    app()->isLocal() ? BreakpointBadgePlugin::make() : null,
]))

or wrap the whole ->plugins([...]) call in an environment check. Doing this at the panel-provider level is better than a runtime config flag, because it also avoids loading the package's assets in production at all.

Use a dedicated dev panel for heavy UI work. If you already have a local-only panel (or a ->default() dev panel), put the badge there and leave your real panels untouched. This keeps the blast radius at zero and means you never have to remember to remove it.

Pair it with your Tailwind config. The badge is only useful if the breakpoints it reports match the ones your Filament theme actually compiles with. If you have a custom theme with overridden screens, verify the package reads the same values (or configure it to match) — otherwise you'll be debugging a layout against the wrong number.

Treat it as a QA aid, not a feature. The natural workflow is: open the panel in a resizable window, drag to each breakpoint, note the class that changes, adjust your ->gridColumns() / ->columns() / custom widget CSS, reload. Don't build tests or business logic around it; it's a visual instrument.

Multi-panel setups. If you run several panels, register it once in the panel you develop in, not everywhere. Duplicated badges across panels is the usual symptom of copy-pasting the provider block.

Upgrade hygiene. v3.0.1 is a maintenance release — Dependabot bumps to actions/checkout@4 and git-auto-commit-action@5, plus refreshed Composer constraints for Laravel 11. There are no new features and no breaking changes relative to v3.0.0. If you're coming from 2.x, the breaking changes live in v3.0.0 (Filament v3 alignment) — review that changelog, not this one. Practically: bump the constraint, run composer update chrisreedio/filament-breakpoint-badge, clear caches, and confirm the badge still renders.

Gotchas and Tips

• The Laravel 11 blocker is resolved here, not in 3.0.0. If composer require failed on a Laravel 11 app with a dependency conflict, that's the symptom v3.0.1 fixes. Don't work around it with --ignore-platform-reqs or a replace hack; just require ^3.0.1.
• Cached config will hide a plugin registration change. Filament panel configuration is resolved per-request but if you've run config:cache or route:cache in a local environment (some teams do it in CI-parity setups), changes to the provider appear to do nothing. php artisan optimize:clear first, then debug.
• Assets not loading = blank or unstyled badge. Filament plugin assets are served through the panel's asset pipeline. After installing or upgrading, run php artisan filament:upgrade. If you publish Filament assets into public/, remember to re-publish.
• Breakpoint mismatch is the #1 "it's broken" report. The badge reports client-side viewport breakpoints; your Filament layout may be constrained by a max-width container, so the container breakpoint and the viewport breakpoint diverge. Resize the container, not just the window, when validating.
• Don't leave it enabled "just in case" in shared environments. Screenshots in bug reports and stakeholder demos with a stray breakpoint badge in the corner are a small but recurring embarrassment. Environment-gate it and be done.
• Debugging a missing badge: check in order (1) plugin is in the correct panel's plugins() array, (2) you're actually viewing that panel's route, (3) assets published/upgraded, (4) config cache cleared. In a package this small, those four cover essentially every failure mode.
• Extension points are limited by design. Expect the plugin class plus possibly a publishable view/config. If you need the badge styled differently, prefer publishing/overriding the view over forking — the package is actively (if lightly) maintained, and a fork will drift on the next Filament major.
• Version alignment matters more than the patch number. This package tracks Filament v3. Before upgrading Filament, check the package's composer.json constraints rather than assuming ^3.x of the plugin covers ^3.x of Filament.