Filament Echarts Laravel Package

Technical Evaluation

Architecture fit. elemind/filament-echarts is a thin integration layer, not a charting engine. Its architectural job is narrow and well-defined: register the Apache ECharts JS bundle through Filament's asset pipeline, expose a Livewire widget (or Blade component) that accepts an ECharts option array from PHP, serialize it to JSON, and hand it to Alpine for client-side initialization. That is a natural fit for Filament's plugin model — Filament is itself a Laravel package that expects third-party panels to register assets via FilamentAsset::register() and widgets via Livewire components. The package does not need to touch Eloquent, routing, auth, or the panel lifecycle, so its blast radius inside a Laravel app is small.

The architectural caveat is that the glue sits on the two fastest-moving surfaces in the Filament stack: the asset registry (which changed shape between Filament v3 and v4) and the Livewire render/morph lifecycle (v3 → v4). A package this thin has little internal surface area to absorb churn, so its long-term viability is almost entirely a function of whether the maintainer keeps pace with Filament majors.

Integration feasibility. Mechanically straightforward: composer require, register the plugin in the PanelProvider, publish/compile assets. Expect hours, not weeks, for a first chart. The real feasibility questions are behavioral, not procedural:

• PHP → JS function bridging. ECharts options frequently require JavaScript callbacks (tooltip.formatter, axisLabel.formatter, symbolSize, rich-text label renderers). A PHP-array-only API either drops these, accepts raw strings (escaping/XSS exposure), or requires Laravel's Js::from() and a serialization contract. This is the single most common failure point in ECharts wrappers and determines whether the package is a toy or production-grade.
• Data transport. If chart series are passed as public Livewire properties, every poll and every interaction round-trips the full dataset over the wire. For dashboards with meaningful row counts, that is a performance trap the package may or may not mitigate.
• Lifecycle correctness. Charts must survive wire:navigate SPA transitions, Livewire re-renders, and tab/visibility toggles — requiring wire:ignore, explicit dispose(), resize observers, and setOption(..., { notMerge: true }) semantics. Getting this wrong produces blank-canvas bugs that are intermittent and expensive to diagnose.

Technical risk.

Note the aggregate score (17.4/100) and zero dependents. That is not a statement about code quality — it is a statement about unvalidated supply chain. Treat the package as a well-scoped prototype accelerator, not an infrastructure dependency, until it clears an internal audit.

Key questions to answer before adoption.

1. Which Filament majors (^3.x, ^4.x) and Livewire versions are constrained in composer.json? Is the constraint honest, and is there a CI matrix proving it?
2. Does it extend Filament's ChartWidget / Widget contract, or ship a parallel abstraction? Contract alignment determines whether it inherits filters, polling, lazy-loading, and column-span behavior for free.
3. How are JS callbacks expressed? Js::from(), raw strings, or unsupported? What is the escaping story?
4. Are assets registered globally or per-widget? Is the ECharts bundle tree-shaken or the full ~1MB build?
5. How is data delivered — Livewire properties, a JSON endpoint, or lazy fetch? Is there server-side downsampling?
6. What is the re-init story for wire:navigate, polling, and re-render? Any documented dispose() handling?
7. Test suite, CI, static analysis, SECURITY.md, release cadence, and issue responsiveness?
8. Is PHP 8.2+/Laravel 11/12 supported, and does it pass composer audit cleanly?

Integration Approach

Stack fit. Laravel 11/12 + Filament 3.x or 4.x + Livewire 3 + an existing Vite/Tailwind theme. The package should slot in as a panel plugin alongside your existing theme build, with ECharts loaded through Filament's asset registry rather than a hand-rolled <script> tag. If your panel already uses a custom Vite theme, confirm the package doesn't double-register assets or fight your bundler.

Migration path. Do not rip out Filament's built-in Chart.js widgets. Run them in parallel and migrate per chart type, on the basis of capability gap rather than novelty:

• Keep Chart.js for line/bar/pie/doughnut with standard tooltips and modest data volumes — it's first-party, maintained, and zero added risk.
• Adopt ECharts where Chart.js genuinely cannot compete: heatmaps, sankey, candlestick, geo/map, Gantt-style, tree, radar, and large-series rendering (large: true, dataZoom, progressive rendering).
• Migration mechanics: introduce an internal base class (e.g. App\Support\Charts\BaseEchartsWidget) that extends the package's widget, owns the option-building DTO, and centralizes theme tokens, resize handling, and wire:ignore/dispose behavior. All application widgets extend your class, never the vendor class directly. This is the swap seam — if the package is abandoned, you replace one file's parent class.

Compatibility. Pin exact package versions in composer.json (not ^), commit composer.lock, and treat Filament upgrades as gated events: upgrade Filament in a branch, run the panel's chart regression matrix, then merge. Verify that php artisan filament:assets (v3) or the Vite theme build (v4) correctly emits the ECharts bundle in your deploy pipeline — asset-publication omissions are the number-one cause of "chart blank in staging" failures.

Sequencing.

1. Week 1 — spike. Non-critical internal panel, one ECharts-only chart type (e.g. heatmap). Validate CSP, asset pipeline, wire:navigate, polling, and a JS-formatter callback end to end.
2. Week 2 — containment. Build the internal base widget + option DTO; write a short ADR documenting why the package was adopted and the fork trigger conditions.
3. Weeks 3–5 — targeted rollout. Convert 3–5 high-value advanced charts. Leave everything else on Chart.js.
4. Ongoing — gate. Track Filament majors and the package's release activity quarterly. If the package lags a Filament major by more than one release cycle, execute the fork or replace the parent class.

Verdict: Adopt with containment for advanced visualizations only. Not an approved default charting layer, and not on the critical path for anything customer-facing without a vendored fork.

Operational Impact

Maintenance. Assume you own it. With 15 stars, zero dependents, and a single maintainer, budget for a vendored fork within 12 months: fork to a private VCS or path repository, and keep the diff to upstream minimal so re-syncs stay trivial. Ongoing cost is modest — the package is small, so a fork is measured in hours per Filament major, not weeks — but the obligation is real and should be assigned to a named owner. Add it to the dependency-review checklist and composer audit gate.

Support. No vendor SLA, no commercial backing. Support channels are GitHub issues and the Filament Discord. Mitigate with an internal runbook covering: asset rebuild after deploy, chart-blank triage steps, CSP exceptions, and the fork-and-patch procedure. Expect the team — not the maintainer — to be the escalation path.

Scaling. Three distinct axes:

• Bundle/load. ECharts is heavy relative to Chart.js. Full builds approach ~1MB; tree-shaken builds land far lower. Load it lazily (only on pages that render ECharts widgets) and confirm the package supports deferred registration, or add it at the theme layer yourself. A dashboard with six chart widgets on a cold admin load is a real perceived-performance regression versus Chart.js.
• Data volume. Push aggregation to the database, not to PHP arrays. Downsample server-side to at most a few thousand points per series, and prefer a dedicated JSON endpoint + fetch over Livewire property transport for large series. Cache expensive aggregates.
• Concurrency. Polling widgets multiply request volume. Keep poll intervals ≥30s for dashboards, and ensure charts update in place rather than re-instantiating. Undisposed ECharts instances leak canvas and WebGL-like memory over long-lived admin sessions; verify dispose() on Livewire teardown.

Failure modes to instrument and document.

• Blank canvas after wire:navigate or a tab switch (missing re-init / wire:ignore mishandled) — the highest-frequency field failure.
• Asset 404 after deploy (bundle not published/compiled) — silent, environment-specific, breaks only charts.
• CSP violation blocking inline option initialization — surfaces as a console error and an empty div; needs a nonce story.
• Memory growth from undisposed instances on long sessions with polling.
• XSS via unescaped option strings when user-supplied labels or formats flow into the ECharts config — enforce escaping at the DTO boundary.
• Precision/locale drift: JSON-encoded large integers on the PHP→JS boundary, and timezone-sensitive axis labels rendering differently for the viewer than for the server.
• Silent breakage on Filament upgrade — mitigated only by the gated-upgrade process.

Add browser-side error reporting (Sentry or equivalent) with a tag for chart-init failures; server logs will never see these.

Ramp-up. A Laravel developer comfortable with Filament and Livewire reaches a first working chart in 1–2 days. Proficiency is gated by the ECharts option API, which is large and idiosyncratic — budget 1–2 weeks for a developer to be independently productive across non-trivial chart types, plus documentation of your internal DTO and base-widget conventions so the patterns don't get reinvented per dashboard. Total onboarding investment is small; the durable cost is the standing ownership obligation created by the dependency's immaturity.