Heroicon Laravel Package

Getting Started

This package provides Heroicons (and some Font Awesome icons) as usable components inside Laravel Nova. The v2.0.0 release is a Nova 4-only line; if your app is still on Nova 3, you must require ^1.0 instead — the two majors are not interchangeable.

Minimal steps:

1. Install the version matching your Nova major:

   # Nova 4 projects
   composer require azartsev/heroicon:^2.0
   
   # Nova 3 projects (do not upgrade)
   composer require azartsev/heroicon:^1.0
   

2. Check the package's service provider is auto-discovered (standard Laravel package discovery); no manual registration should be needed.
3. Look first at the package's README and src/ directory to see the exact component/helper names exposed. The API surface is small — the practical entry point is referencing icons from your Nova resources, fields, and custom tool templates.
4. First use case: drop an icon into a Nova resource's navigationIcon() or a custom card/tool's Blade view. Start with one icon, confirm it renders in both light and dark Nova themes, then roll it out.

Note the release explicitly lists "Fix few heroicons" — if you pinned specific icon names in v1, verify each one still exists and renders correctly after upgrading.

Implementation Patterns

Version pinning as a first-class concern. Because v2 is breaking, treat the composer constraint as part of your deployment contract. In a monorepo or multi-app setup with mixed Nova versions, keep separate lockfiles and never let a blanket composer update float one app onto ^2.0.

Icon references in Nova resources. The most common workflow is static icon identifiers in resource classes. Centralize these (e.g. a small config map or enum) rather than scattering raw strings, so the Nova 3 → 4 icon migration is a one-file change.

Theme-aware rendering. v2 changed styles to support light and dark themes. In custom tool/card Blade views, avoid hardcoding fill, stroke, or colors — let the package's styling and Nova's theme classes drive appearance. Test in both themes in the Nova UI, since Nova 4's theme handling differs from Nova 3.

fill='currentColor' on Font Awesome icons. v2 sets currentColor on Font Awesome icons, meaning they inherit text color. Use this deliberately: wrap icons in elements whose text color you control, and you get theme-correct icons for free. If you were previously relying on an explicit fill applied by the package, remove your overrides.

Upgrade workflow. For an existing install, the documented path is simply bumping composer.json from ^1.0 to ^2.0, then composer update azartsev/heroicon. Do this on a branch, run your app's Nova pages in both themes, and diff any custom icon-heavy views before merging.

Custom tools/cards. Use these as the place to standardize icon usage across your admin panel — a shared Blade partial or wrapper component that renders the package's icons keeps theme behavior consistent and makes a future major bump a single-file fix.

Gotchas and Tips

• Breaking change is Nova-version-gated, not feature-gated. v2 simply won't work on Nova 3. The failure mode is likely runtime/rendering rather than an install error, so don't rely on Composer to catch a mismatch — check your Nova version explicitly before upgrading.
• Composer constraint mistakes are silent until deploy. A ^1.0 || ^2.0 style constraint would let Composer resolve v2 in a Nova 3 app. Pin strictly per environment.
• Renamed/removed icons. "Fix few heroicons" means some icon identifiers or their markup changed. Grep your codebase for icon strings and spot-check each in the UI after upgrading.
• Theme regressions. The style changes for light/dark support are visual — any custom CSS that targeted the package's SVG output (stroke widths, fills, sizing) may now conflict or be overridden. Inspect computed styles rather than assuming.
• Font Awesome currentColor interaction. If an icon appears the wrong color, check the inherited color on ancestors before adding your own fill — the new default is inheritance, and local overrides are the usual culprit.
• Debugging rendering issues. Inspect the rendered SVG in the browser first; most issues are missing/wrong icon names or CSS overrides, not package faults. Confirm the resolved package version with composer show azartsev/heroicon before filing anything.
• Extension point. Since icons are just SVG output, wrapping the package in your own Blade partial is the safest customization layer — it survives future majors better than editing vendor output or overriding styles globally.
• Pin exact minors for critical admin panels. Given the visual changes in this release, prefer ^2.0 with a committed lockfile and review changelogs on minor bumps.