Blade Eos Icons Laravel Package

Technical Evaluation

Architecture fit codeat3/blade-eos-icons is a presentation-layer leaf dependency. It registers Blade components that render EOS Icons SVGs by delegating to blade-ui-kit/blade-icons; it introduces no routes, migrations, queues, scheduled jobs, persistence, or runtime configuration that alters application behaviour. For a TPM the practical consequence is that this package carries no architecture-review weight — it cannot constrain the service graph, the data model, or deployment topology. The only decisions it participates in are design-system decisions: which icon language the product speaks, and whether icon rendering sits behind an abstraction we control. Treat it as a design-asset line item and a dependency-audit checkbox, not a platform component.

TPM leverage is therefore concentrated in three planning artefacts rather than in engineering: the icon-set standardisation decision, the Laravel major-version upgrade checklist, and the reversibility of the dependency — how fast we could remove it if the maintainer walks away.

Integration feasibility High and cheap to trial. Adoption is one composer require codeat3/blade-eos-icons plus template edits. Auto-discovery removes service-provider wiring; no assets need publishing on the default path; no build step is introduced. The component surface is one tag per glyph, and the SVG filename is the component name — an inventory we can enumerate from the vendor directory rather than from a marketing page. A meaningful pilot is one feature area plus a wrapper component, roughly a day of work, and it produces a reversible decision.

Technical risk Four risks matter, in descending order:

1. Bus-factor one. Single maintainer, one star, zero dependents, no SLA, no documented CVE process. Acceptable for view-layer decoration; unacceptable as an untouchable dependency.
2. Transitive gate on Laravel 13. Release 1.16.0 widens the framework constraint only. The real go/no-go is whether the resolved blade-ui-kit/blade-icons version in our lockfile declares Laravel 13 support. This must be verified against the lockfile, not the changelog.
3. Payload growth. Each icon instance inlines a full SVG; density scales linearly. Dense tables and nav bars are the one place this can measurably hurt.
4. Correctness edge cases. Duplicate id attributes when the same glyph renders twice on a page (broken masks, invalid HTML), stale caches after composer update, and Blade formatters mangling self-closing component tags.

None of these are blockers. All of them are neutralised by two cheap decisions: pin the version, and consume the package only through our own wrapper.

Key questions

• Do designers actually want EOS Icons, or is this a placeholder for a set decision not yet made? It is a niche, outline-oriented, technical vocabulary.
• How many glyphs do we genuinely need? If the answer is under ~20, vendoring the SVGs into resources/ removes the dependency entirely.
• Is our frontend strategy staying server-rendered Blade? Inertia/React or API-only surfaces get no value here.
• Who owns the wrapper component and the name→variant map, and where does it live?
• Is the Laravel 13 bump landing in the same PR as the framework upgrade, so resolution is bisectable?

Integration Approach

Stack fit Native to Laravel Blade and Tailwind. Icons inherit fill="currentColor", so text-* utilities colour them and size-* sizes them; no CSS pipeline or asset build changes are required. Livewire works unchanged, with the caveat that every re-render re-emits full inline markup. If the team is already on blade-icons for any other set, this is additive and consistent; if the team has no icon strategy, adopting this ratifies one — make that call explicitly rather than by default.

Migration path The migration is not "install the package", it is "install the package and immediately hide it." Sequence:

1. Pin ^1.16 in composer.json and commit the lockfile.
2. Add one wrapper (resources/views/components/ui/icon.blade.php) holding the name→component map, defaults for sizing, and the accessibility branch (aria-hidden vs role="img" + aria-label).
3. Establish the rule — feature templates never reference x-eos-icons::* directly — and document it in a paragraph, not an icon guide page.
4. Pilot 8–12 glyphs in a nav/sidebar/button set.
5. Only then expand.

If migrating off an incumbent set, run the pilot in one feature area and judge it on real screens. The wrapper makes the swap a one-file change in either direction.

Compatibility Two compatibility facts to verify rather than assume: the exact registered component naming (eos-icons-* prefix, variant suffixes such as -outlined, -filled, -round, -sharp, -two-tone), which should be confirmed by reading the vendor SVG directory and the service provider rather than the README; and the resolved blade-icons version in the lockfile. Also verify that Prettier or any Blade plugin in CI preserves self-closing component tags through a format pass.

Sequencing Land the version bump in the same PR as the framework upgrade, or immediately preceding it, so any resolution failure is attributable. Wire php artisan icons:clear (confirm the exact command via php artisan list icons) into the deploy sequence after composer install and before view:cache, and into the post-composer update runbook. Add a CI test that renders every mapped component and asserts <svg in the output — an upstream rename then fails the build instead of production. Nothing here belongs on a roadmap: it is a checkbox inside the Laravel upgrade workstream.

Operational Impact

Maintenance Steady-state is effectively zero. No cron, no queue, no storage, no config to publish — the package ships neither config nor views. Upstream releases have so far been constraint-widening and icon-set refreshes; 1.16.0 changes no API, naming, or config. The recurring cost is the wrapper map: when a glyph we use is renamed upstream, our CI smoke test catches it and someone edits one file. Budget that as minutes, not days.

Support There is no support channel. No SLA, no security response process, one maintainer. Our support story is self-supplied: the wrapper isolates blast radius, the pinned version prevents surprise breakage, and the exit path — copying the 10–20 SVGs we actually use into resources/svg/ — is an afternoon of work. That exit must stay credible; if the wrapper's map grows to hundreds of entries, the exit stops being cheap and the risk profile changes. Review the map size at each major milestone.

Scaling Two scaling dimensions:

• Request/render scale. Inline SVG grows linearly with icon density. Sixty icons in a dense table is sixty copies of markup per request. Mitigate with a memoised wrapper or a sprite strategy; do not reach for a CDN, which sacrifices the currentColor inheritance that makes the wrapper work.
• Organisational scale. More teams means more call sites. The wrapper plus the "no direct package references" rule is what keeps the icon vocabulary consistent as contributors multiply. Without it, three half-used icon sets accumulate as design debt.

Failure modes

Most "the package broke" reports are cache staleness, not code. Put that first in the runbook.

Ramp-up Near zero for any engineer who has used Blade components. The only learning is the wrapper convention and the accessibility rule, both of which are enforced by the wrapper rather than taught. A new contributor ships correct icons on first use without knowing the package exists — which is the correct outcome, and the strongest argument for the wrapper being part of the initial integration rather than a later cleanup.