Filament Dashboard Widgets Laravel Package

Technical Evaluation

Architecture fit

• Targets Filament's native extension surface (Filament\Widgets\Widget / ChartWidget subclasses rendered by Livewire on the panel dashboard), so it slots into an existing Laravel/Filament admin without a new front-end stack, build pipeline, or JS dependency graph.
• Value proposition is commodity UI: KPI cards, goal progress, breakdowns, trends, funnels, timelines. These are consistently rebuilt per project, so the package converts recurring internal design/dev cost into an install — attractive for agencies and internal-tools teams running multiple Filament panels.
• v1.0.1 strengthens the "native" story: cards now match Filament's surface, ring, shadow, type scale, icon backgrounds, row dividers and focus ring, so widgets no longer look foreign next to hand-built ones. That reduces the classic "third-party widget aesthetic" objection that blocks adoption in design-conscious panels.
• The typed API and "fifteen widgets, one consistent contract" story is the real architectural asset — it gives us a uniform widget authoring model rather than fifteen bespoke Blade partials.

Integration feasibility

• Low integration effort in the happy path: Composer install, optional view/config publishing, register widgets in the panel provider (or rely on discoverWidgets). No queue workers, migrations, or external services implied.
• v1.0.1 changes the asset story: the stylesheet is published as a browser-cached Filament asset (php artisan filament:assets, usually triggered via filament:upgrade) with inline fallback. This is a net improvement — it decouples widget styling from the host Tailwind build — but it introduces an explicit asset-publish step to verify in CI/staging.
• Real work is not installation but data plumbing: each widget needs a query or pre-computed dataset, and we must decide per widget whether it accepts an Eloquent builder, a closure, or a static array — that determines query count and multi-tenant scoping strategy.
• Feasible in a single sprint for one panel; feasible across a fleet of panels if we standardize on a shared base widget and a data-provider convention internally.

Technical risk

• Version coupling (high): Filament ships breaking majors on a roughly annual cadence (v3 → v4 changed Tailwind v4 assumptions, asset handling, and several widget/panel APIs). A 15-widget package with a small maintainer is structurally exposed to this; each Filament major is a potential hard fork point for us.
• Adoption signal (high): 7 stars, 0 dependents, single-vendor authorship. There is no ecosystem proof that the Blade/Tailwind output survives real custom themes, dark mode, RTL, or dense dashboards.
• Styling/asset coupling (reduced to medium): v1.0.1 serves the stylesheet as a cached Filament asset with inline fallback and aligns markup to native Filament. This is the right fix and materially lowers the "custom theme renders unstyled" risk — but the publish step (filament:assets / filament:upgrade) must be wired into our release process, and custom themes still need a smoke test.
• Security posture (new, low): v1.0.1 restricts colour names in color() / badgeColor() to [a-zA-Z0-9_-]. Not XSS (Blade escaping held), but it confirms these setters write into CSS and must never receive untrusted input. Acceptable now; we should still treat colour arguments as developer-authored constants.
• Correctness in aggregates (medium): trend/timeline/variance widgets encode date bucketing, timezone, and null/divide-by-zero behavior. These are exactly where "looks right in the demo" diverges from "correct in production."
• API stability (medium): 1.0.x with a documented changelog and upgrading guide; v1.0.1 is explicitly non-breaking. Blast radius of minor bumps still unknown without tracking the changelog.

Key questions

1. Does it extend ChartWidget (pulling Filament's charting stack / Chart.js) or render custom Blade + Alpine? This determines JS asset risk and whether charts are themable/exportable.
2. What is the supported compatibility matrix — Filament v3 only, v4, both? PHP 8.2/8.3, Laravel 11/12? Is it in CI, and is the matrix tested or just declared?
3. What is the data contract per widget: Eloquent builder + closure, raw arrays, or a dedicated data object? Can we inject a cached/aggregated source rather than hitting base tables on every render?
4. Does it honor Filament authorization (canView()), panel tenancy scoping, and per-widget pollingInterval? Can polling be disabled globally?
5. Are views publishable and are classes overridable, i.e. can we patch a widget's behavior without forking the package?
6. Are there locale/currency/number-format hooks? Partially answered by v1.0.1: numbers and percentages now follow the application locale (1 234,5 / 25 %). Still open: explicit currency symbol/placement control, RTL, dark mode, and narrow-breakpoint behavior.
7. Test coverage per widget, and is there a rendering snapshot test we can inherit when we upgrade Filament?
8. Maintainer responsiveness/roadmap: agency-backed and used in their own client work (good), or a one-off publish (bad)? Issue and PR latency is the leading indicator. v1.0.1 (security fix + polish + changelog + upgrade guide) is a positive early signal, not yet proof of cadence.

Integration Approach

Stack fit

• Assumes Laravel + Filament + Livewire; no Node toolchain required beyond the host app's existing Filament theme build. That matches a conventional Laravel monolith or modular monolith with one or more Filament panels.
• Cleanest in panels where the dashboard is the primary landing surface and widgets can be composed per-role. Awkward where dashboards are highly bespoke (custom canvas layouts, embedded BI, drill-down navigation) — the widgets are terminal views, not interactive analysis surfaces.

Migration path

• Introduce incrementally: install, publish config/views, run php artisan filament:upgrade (or filament:assets) so the cached stylesheet is published, and replace one legacy dashboard section at a time. No data migration is implied; the package reads existing models.
• Guard against lock-in with a thin internal adapter: our own abstract base widget (or a small set of wrapper classes) that our panels register, which in turn extend/compose the package widgets. Swapping to in-house widgets later then becomes a class-body change rather than a panel-wide rewrite.
• Pin the exact version in composer.json (no floating ^ across Filament majors), commit the lockfile, and record the package in an ADR with an explicit re-evaluation trigger (Filament major upgrade or >90 days of unaddressed issues).

Compatibility

• Pre-flight: confirm the package's declared constraints against our Filament, Livewire, Laravel, and PHP versions; verify the asset publish step (filament:assets / filament:upgrade) is part of the deploy pipeline; confirm Chart.js availability if it piggybacks on ChartWidget.
• If we already publish package views, v1.0.1 is drop-in (composer update), but the upgrade guide lists two optional markup changes to adopt the native card styling — schedule those on the pilot panel before wider rollout.
• Verify multi-tenant behavior explicitly — if our panels use Filament tenancy, unscoped aggregate queries are a data-leak class of bug, not a cosmetic one.
• Check that canView()/policy integration exists so role-based dashboards don't require us to re-implement gating per widget.

Sequencing

1. Spike (0.5–1 day): install v1.0.1 in a scratch panel, render all fifteen widgets against realistic data volumes, capture query counts and rendered HTML; confirm the published asset path and locale formatting; read the changelog/upgrading guide for breaking-change patterns.
2. Fitness check (1 day): confirm dark mode, mobile breakpoints, currency formatting, tenancy scoping, authorization, and theme/Tailwind interaction (now via published asset rather than host content paths). Decide build-vs-buy against an in-house estimate (~3–6 dev-days for equivalent widgets).
3. Pilot (2–3 days): ship 3–4 widgets (one metric, one goal, one trend, one recent-items) on a single internal or low-risk panel, behind the internal adapter, with caching on the aggregate queries.
4. Measure: widget render time, dashboard query count, cache hit rate, any N+1s from recent-items lists, and asset load behavior under a custom theme.
5. Rollout (per panel): expand to remaining widgets and panels only after the pilot's query profile is acceptable; document widget registration, data-provider and asset-publish conventions in the internal handbook.
6. Fallback: if the pilot fails on compatibility or correctness, keep the adapter and implement the four widgets in-house — the pilot work is not wasted.

Operational Impact

Maintenance

• Ownership cost is dominated by upgrade tracking, not bug-fixing. Budget a recurring line item: each Filament major requires verifying the package (or forking it) before we can upgrade the panel. Treat the package as a dependency with a named internal owner.
• Low bus-factor on the upstream side (small team, low visibility). Assume we may need to fork; ensure MIT license terms are recorded and that forking is permissible under our policy (they are, but note attribution). v1.0.1 — a prompt security fix plus documented upgrade guide — is an encouraging sign of active maintenance and lowers the abandonment prior somewhat.
• Our own maintenance surface is small if the adapter layer is thin: widget registration, data providers, caching config, and the asset-publish step.

Support

• MIT, community-only, no SLA. Support model is GitHub issues with unknown latency. Escalation path is "read the source, patch locally, or fork." That is acceptable for internal dashboards; risky for client-facing deliverables with contractual uptime.
• Mitigation: vendor the source into a private fork (or a patches workflow) after the pilot so a maintainer going quiet doesn't block us.

Scaling

• Dashboards are a query amplifier: N widgets ≈ N+ aggregate queries per dashboard load, and several are COUNT/SUM/date-bucketed scans over large tables. On a 10M-row table, an unpinned trend widget is a slow-query generator.
• Required controls: cache widget datasets (short TTL, per-tenant key), drive widgets from pre-aggregated/daily-rollup tables where volume warrants, cap pollingInterval or disable polling, and consider a read replica for dashboard traffic.
• Render cost is Livewire round-trips per poll; with many concurrent admins polling, this becomes a steady background load rather than a burst. Quantify in the pilot rather than assume.

Failure modes

• Filament upgrade → widget breakage: class signature or view contract changes; symptom is a 500 on the dashboard, potentially taking down the primary landing page for all admin users. Mitigation: pin, upgrade in staging, register widgets defensively.
• Asset not published after upgrade / theme mismatch: widgets fall back to inlined styles (functional, not cached) or render with stale styling under a custom theme. Lower severity than pre-v1.0.1 — the released asset approach plus native parity largely removes the "raw HTML" failure — but the publish step (filament:upgrade / filament:assets) must be enforced in deploy.
• Colour input abuse: a widget given untrusted input to color() / badgeColor() could append arbitrary CSS declarations. Fixed in v1.0.1 (allowlist [a-zA-Z0-9_-]), and never XSS because Blade escapes attributes — but treat colour arguments as static developer-authored values.
• Unscoped queries under tenancy: cross-tenant data appearing in a breakdown or recent-items list. Highest-severity failure mode; must be tested explicitly.
• Aggregate correctness: timezone-off date buckets, division-by-zero in goal progress when target is 0, null handling in variance widgets producing misleading deltas. Wrong-but-plausible numbers are worse than a visible error.
• Recent-items N+1: a "recent items" widget over a relationship-heavy model can emit dozens of queries per render.
• Asset/chart conflicts: if it shares Chart.js with existing custom widgets, duplicate registration or version skew can blank charts across the panel.
• Abandonment: upstream goes dormant; upgrades stall us. Fork is the only exit and should be pre-planned, not improvised.

Ramp-up

• Low technical ramp-up: a mid-level Laravel dev familiar with Filament can integrate and register widgets in under a day; the typed API is the main thing to read. The v1.0.1 native styling now means less design review is required to ship widgets into an existing panel.
• Non-obvious learning is on the data side: choosing cached aggregates vs live queries, and codifying tenancy/authorization conventions per widget. That's ~1–2 days of internal documentation and one reference implementation to institutionalize.
• Onboarding cost is mostly cultural: the team must adopt the "one widget = one data provider + one cache key" convention, or the package becomes fifteen snowflakes instead of a standard.

TPM recommendation: Conditionally adopt for internal and low-risk Filament panels, behind a thin internal adapter, gated on a one-day spike that confirms Filament version support, tenancy scoping, and dashboard query counts. v1.0.1 is a meaningful positive delta — localized number formatting, the cached-native asset path, and the colour-sanitization fix each retire a risk we flagged, and the documented upgrade guide is an early maintenance-cadence signal. It does not change the recommendation, however: do not adopt for client-facing, multi-tenant, or contractually-supported dashboards until the compatibility matrix, canView() support, and aggregate-query behavior are verified and the fork/exit path is documented. The overall risk profile shifts modestly downward on styling and locale, while version-coupling and adoption-signal risk remain the dominant concerns pending broader usage evidence. Worth the spike; still not worth an unconditional bet.