Blade Selfhst Icons Laravel Package

Technical Evaluation

Architecture fit. robertboes/blade-selfhst-icons is a thin Blade component package that vendors the selfh.st icon set as SVG and exposes it through Laravel's anonymous/class component auto-discovery. There is no runtime service, no database surface, no queue or cache dependency, and no JS build step — it composes into the view layer only. For a Blade-rendered Laravel app this is a clean architectural fit with effectively zero footprint. For any part of the product rendered by Inertia/Vue/React or a separate SPA, the package is unusable — the integration boundary is the Blade template, and that boundary should be stated explicitly before adoption.

Integration feasibility. One composer require, one component tag per icon. Realistic effort is a few hours for a first slice including naming discovery, not a sprint. There is no auth, tenancy, migration, or config-publishing story to design around.

Technical risk. The material risk is not code quality, it is the versioning contract. The package is pre-1.0 (0.3.x), so semver carries no stability guarantee, and v0.3.12 illustrates the concrete failure mode: a patch release that adds 15 icons and removes 1. Icon names are the de facto public API here, so an icon removal in a point release is a silent breaking change for any template referencing that name — and a missing Blade component in a loop or conditional can degrade to a blank space rather than a loud error. Secondary risks: single-maintainer project; the icon set is a derivative of a third-party brand asset collection, so licensing/trademark usage for customer-facing product marks needs confirming; and the removal was not accompanied by a deprecation notice in the release notes.

Key questions. (1) Is the icon slug considered a stable public contract, and is there a deprecation policy for removals? (2) Which icon was removed in #42, and do we reference it? (3) Are SVGs shipped in the package or resolved at runtime? (4) What is the license of the underlying selfh.st assets for commercial/hosted use? (5) Who owns upgrades internally if upstream goes quiet?

Integration Approach

Stack fit. Laravel with Blade views, PHP 8.x. Confirm the package's Illuminate support range against our Laravel minor before committing. No front-end toolchain impact, which makes this a low-blast-radius dependency.

Migration path. Two realistic origins: hand-rolled <img>/inline SVG in templates, or an incumbent icon package (Blade Heroicons, Font Awesome, etc.). The second is more work than it looks — icon naming differs across sets, so a mechanical swap will produce wrong or missing glyphs. Budget an explicit name-mapping pass over the icons actually in use rather than a find-and-replace. A useful intermediate step is to introduce one internal wrapper component (e.g. <x-app-icon>) that delegates to the package, so a future swap-out or pin-down is a single-file change.

Compatibility. Pin to ~0.3.12 or an exact version rather than ^0.3, precisely because v0.3.12 demonstrates that patch releases can drop icons. Treat every upstream bump as a reviewable change, not an auto-merge — dependabot/Renovate should route these to a human.

Sequencing. (1) Inventory every icon currently referenced in templates; (2) verify all of them exist at v0.3.12; (3) add the dependency and the internal wrapper component on a branch; (4) migrate one low-traffic view, visually diff; (5) roll out view-by-view; (6) only then consider removing the incumbent icon package. Do not do the add and the remove in the same release.

Operational Impact

Maintenance. Ongoing cost is low but non-zero and external: upstream is a solo-maintainer project whose release cadence is driven by third-party icon churn, not by our roadmap. Expect frequent trivial releases. Our maintenance burden is really "review the diff on each bump," which is cheap if the wrapper component exists and expensive if icon names are scattered across templates.

Support. No commercial support, no SLA, community issues only. That is acceptable for a cosmetic dependency but means internal ownership must be named. Mitigating factor: the payload is static SVG, so the worst case — abandonment — is recoverable by vendoring the assets ourselves in under a day.

Scaling. Rendering cost is negligible; Blade only emits the icons actually invoked. The scaling concern is repository and view-layer bloat as the icon set grows, plus the cognitive cost of an unvetted catalogue — teams tend to accumulate inconsistent icon usage when hundreds are one tag away. Consider a short allowlist in code review.

Failure modes. (a) Silent icon loss — an upstream removal (as in v0.3.12) blanks an icon in production with no exception; this is the most likely incident and is best caught by a visual regression check or a template-level test asserting referenced icon names exist. (b) Loose pin drift — ^0.3 lets a removal arrive unreviewed. (c) Scope mismatch — a team assumes it works in an Inertia/Vue view and discovers otherwise mid-sprint. (d) Licensing exposure — third-party marks rendered in a commercial UI without a cleared license.

Ramp-up. Near-zero for any Laravel developer; the component syntax is idiomatic Blade. The only learning is the naming convention and the internal wrapper's props. Documentation burden is a single paragraph in the team's front-end conventions doc.

Assessment of v0.3.12 specifically. Net: adopt, pinned, with a review gate. The release is functionally additive (15 icons) but carries one removal in a patch version — minor in isolation, meaningful as a signal about how this project versions. No blocker, no deprecation affecting us, no action required beyond confirming the removed icon is not in our inventory before we pin to 0.3.12.