Heroicon Laravel Package

Technical Evaluation

Package context: AlexAzartsev/heroicon is a small Laravel/Nova presentation package that supplies Heroicons and Font Awesome icon sets as selectable assets inside Laravel Nova. It has no domain logic, no persistence layer, and no runtime service surface — it is a UI asset/field helper. That narrowness is the most important fact in this evaluation: the blast radius is visual, not functional.

Architecture fit: Fits cleanly as a leaf dependency in a Nova admin panel. It does not touch application models, queues, auth, or the public-facing app. Integration is composer-only plus, at most, publishing/discovering a Nova field or asset registration. The architectural concern is not coupling — it is that the package's major version is pinned to a Nova major version.

Integration feasibility: High. The upgrade path documented is a single constraint bump (^1.0 → ^2.0). However, that is only true if the host application is already on Nova 4. v2.0.0 deliberately drops Nova 3 support rather than supporting both, so the package version and the Nova version form a hard 1:1 pairing.

Technical risk (ranked):

Key questions before approval:

1. What is the current Nova major version across all properties that use this package, and is the Nova 4 upgrade already complete or in flight?
2. Do we store icon identifiers anywhere durable (DB, config, seeders)? If so, can we enumerate every stored value and confirm it still resolves after "fix few heroicons"?
3. Is the fill='currentColor' change a behavioral fix we want (theme-aware icon tinting) or a silent restyle that conflicts with custom CSS in our panels?
4. Are we willing to own a fork if the maintainer goes dormant before our next Nova major upgrade?
5. Does anything depend on this package outside Nova (e.g. Blade views reusing the icon set)? The package name suggests Nova-only, but confirm.

Integration Approach

Stack fit: Laravel + Nova. No queue, cache, storage, or external service implications. Deployment is a composer install and an asset rebuild; no migrations, no env vars, no config publishing expected beyond what v1 already required.

Migration path and compatibility: The documented path is a one-line constraint change. In practice the correct sequence is the reverse of what the release note implies:

1. Upgrade the host to Nova 4 first (its own breaking migration, entirely independent of this package).
2. Only then bump heroicon to ^2.0.
3. Rebuild frontend assets and purge any published vendor assets, since the style changes ship as CSS.

Attempting the package bump on a Nova 3 host will fail composer resolution — a safe, loud failure. The genuinely unsafe scenario is the opposite: a repo that upgrades this package opportunistically during a routine composer update while its Nova constraint is loose enough to permit it.

Sequencing and guardrails:

• Pin the constraint explicitly in each repo (^1.0 or ^2.0), never a bare * or an unpinned require.
• Do not batch this bump into a general dependency-refresh PR; it should land with the Nova 4 upgrade or immediately after.
• Inventory stored icon names before upgrading, and diff rendered output in both light and dark themes as an explicit acceptance criterion.
• If the fleet must span Nova 3 and Nova 4 for any period, treat the two branches as separate supported lines and document which repos are on which. There is no compatibility shim available.

Rollback: Trivial — revert the constraint and reinstall. The only irreversible element is if any data was rewritten to new icon slugs that do not exist in v1.

Operational Impact

Maintenance: Near-zero steady-state. No scheduled jobs, no runtime dependencies, no data lifecycle. The maintenance burden is concentrated entirely into Nova major-version transitions, which for this package means a forced breaking bump roughly once per Nova cycle.

Support: Thin. Single-maintainer GitHub project; changelog is release-note quality, not support-contract quality. We should treat upstream responsiveness as best-effort and plan for the possibility of a trivial internal fork. Mitigating factor: the package is small enough that forking or vendoring is genuinely cheap — this is a low-severity but non-zero abandonment exposure.

Scaling: Not applicable in the conventional sense. Icon assets add a bounded page-weight and build-time cost. The only scaling-adjacent consideration is build pipeline consistency — every property shipping Nova panels must be on a consistent icon package version to avoid visual drift between environments.

Failure modes:

• Silent visual degradation: unresolved icon slug renders blank or fallback, no exception, no log line. Highest-likelihood failure and the hardest to catch in CI. Mitigate with a smoke-render check on any screen using icons.
• Dark-mode regression: the style and currentColor changes alter existing appearance. Users notice; monitoring does not.
• Dependency deadlock: an unrelated add-on holding nova ^3 blocks the whole upgrade. Loud, but can stall a release train.
• Abandonment: no v3 for Nova 5. Mitigation is fork-and-own, low effort.

Ramp-up: Effectively none for engineers — the package is declarative usage of an icon field. The actual ramp-up cost sits with the Nova 4 upgrade itself, not this dependency. For the TPM, the required knowledge is narrow: know which repos are on which Nova major, and know that the two heroicon lines cannot coexist.

Recommendation: Approve v2.0.0 for properties already on (or imminently moving to) Nova 4, gated on (a) an inventory of persisted icon identifiers, and (b) a light/dark visual diff of representative panels. Hold Nova 3 properties on ^1.0 with an explicit pin and a tracked migration item. Do not treat this as a routine patch bump in automated dependency updates.