Blade Heroicons Upgrader Laravel Package

Product Decisions This Supports

• Whether to take the Heroicons upgrade now, later, or never. This package exists to automate one specific, boring, error-prone job: rewriting Blade Heroicons usage from the v1 naming/syntax to v2. That makes it a scheduling decision as much as a technical one — the upgrade can become a contained one-sprint chore instead of an open-ended "icon refresh" epic.
• Build vs. buy for the migration itself. The alternative is an engineer hand-editing templates or writing a throwaway codemod. Buying (adopting) costs a dev-dependency and a review pass; building costs engineering days plus the risk that the script misses edge cases nobody tests. For a one-time migration, adopting is almost always the cheaper path — provided the dry-run diff looks clean.
• Scope estimation for dependency upgrades. Icon libraries touch many files but few business rules. A tool that produces a reviewable git diff lets you estimate the work by diff size and reviewer hours rather than by guesswork, and gives you a clean rollback point.
• Roadmap sequencing for framework upgrades. The package's install matrix now covers Laravel 10, 11, and 12, which means the icon migration can be bundled into a broader Laravel upgrade branch (or run before it) without worrying about version incompatibility.
• Where it does not help. It does not decide your target icon library, your icon component API, or your design-system abstraction. Those remain product/design calls; this only executes a mechanical rename.
• What v1.2.2 specifically changes for a PM: nothing in scope, cost, or risk profile. It is a quality/CI release — PHPStan config, an install-test script across Laravel 10–12, a composer test-install and an aggregate composer e2e command, 100% coverage, and one type fix in the UpgradeIcons command. The decision-relevant signal is credibility, not capability: a tool that is about to rewrite your templates now has static analysis and a green install matrix. Treat this as a green light on the existing assessment, not a new feature to plan around.

When to Consider This Package

Consider adopting when:

• You are on Blade Heroicons v1 (or the older blade-ui-kit/blade-heroicons component naming) and have decided to move to v2.
• The codebase has enough icon usage that manual find-and-replace is genuinely risky — the rename is not a pure string swap (solid/outline/mini variants and renamed aliases mean a naive regex will silently produce wrong or missing icons, which is worse than a failing build).
• Icons are referenced directly in templates as Blade components/@svg calls, i.e. the thing a codemod can actually see.
• You want a repeatable, reviewable diff: run on a branch, review, revert if unhappy, run again after rebasing.
• You want the migration done but are not ready to commit to a larger design-system or component-library overhaul.

Look elsewhere when:

• You are already on Heroicons v2, or never used v1 — there is no work to do.
• Icons are consumed through your own wrapper/design-system component rather than the vendor component directly. A codemod cannot reason about your abstraction; you need a manual mapping table or a bespoke script.
• Icon names are dynamic — config arrays, database values, variables, string concatenation. Expect these to be missed and budget a manual sweep.
• Your icon consumption lives outside Blade (Vue/React/Livewire inline SVG, a JS build pipeline). You need the JS-side tooling or a manual pass.
• You are working in a large monorepo where a partial rewrite is unacceptable. Prefer a fork you control, or treat the first run as a spike rather than a merge candidate.

Verify before committing: these release notes are internal-only and describe the package's test and analysis setup, not its rewrite rules. Before pointing it at production templates, confirm the command signature, the supported Heroicons v1 → v2 mapping, and whether it supports a dry-run/diff mode. Run it on a throwaway branch first and read the diff.

How to Pitch It (Stakeholders)

Executive summary. This is a small, free, open-source Laravel developer tool that automates a specific tedious upgrade: converting our Blade Heroicons usage from the old v1 component names to v2. It replaces manual template editing — hours of low-value, high-error-rate work — with a scripted change that produces a reviewable diff on a branch and can be thrown away afterwards. Cost is one development-only dependency; there is no runtime footprint in production and no vendor lock-in. The just-published v1.2.2 is a quality release: static analysis (PHPStan), 100% test coverage, an end-to-end test command, and installation verified against Laravel 10, 11, and 12. That is exactly the maturity signal we want before letting a tool touch our templates, and it also confirms compatibility with both our current and target Laravel versions. Recommendation: green-light a timeboxed spike on a branch, review the diff, and decide to merge or discard from there.

For engineering. Composer dev-dependency plus an Artisan command; runs locally or in CI, output is a git diff. No schema, infrastructure, or production dependency changes, so the blast radius is limited to the files it rewrites and is fully reversible via git. The new composer test-install and composer e2e commands mean we can validate the tool against our Laravel version before running it in anger, and the PHPStan + 100% coverage work means the rewrite logic itself is now type-checked and exercised. Known limitation to plan around: dynamically constructed icon names will not be caught — budget a manual audit pass for those.