Blade Heroicons Upgrader Laravel Package

Getting Started

This is a development-time codemod, not a runtime package — it never ships to production. Install it as a dev dependency in the app (or in a package/layout directory) you are migrating:

composer require --dev helgesverre/blade-heroicons-upgrader

First place to look:

1. php artisan list | grep -i icon (or vendor/helgesverre/blade-heroicons-upgrader/src) to confirm the registered command and its options — the release notes reference an UpgradeIcons command class, so verify the exact signature and any flags with php artisan <command> --help.
2. If the package ships a publishable config/mapping, php artisan vendor:publish --tag=... before the first run so you can inspect the old→new icon map.
3. Check composer.json constraints against your Laravel version — v1.2.2's install test matrix now covers Laravel 10, 11 and 12, so all three are verified.

First use case: you bumped blade-ui-kit/blade-heroicons to v2 and your Blade views still reference renamed or removed icons (<x-heroicon-o-...> / <x-heroicon-s-...>). Run the upgrader across resources/views on a clean branch, then review the diff like any other refactor.

Implementation Patterns

Branch-and-diff workflow (the default). Never run a mass rewrite on a dirty tree. Commit or stash, create chore/heroicons-upgrade, run the command over your views, then git diff / git diff --stat to audit every substitution before committing. This is the single highest-value habit with a codemod.

Scope it to real view directories. Point the command at resources/views (and any package view paths) rather than the project root, so it does not walk vendor/, storage/, or compiled caches. If the command only accepts a path argument, run it once per root.

Sequence it with the dependency bump. Bump blade-ui-kit/blade-heroicons first, run composer update, then run the upgrader, then php artisan view:clear and smoke-test the pages that use icons. Doing the component renames before the vendor bump leaves you with icons that render fine but don't exist in the new set — you lose the immediate feedback loop.

CI guard against regressions. After the migration lands, add a check job that runs the upgrader and asserts the working tree is unchanged — it catches anyone copy-pasting old icon names back into a view. Cheap, and it keeps the migration from silently regressing.

Large apps: batch per area. Run it directory-by-directory (resources/views/admin, resources/views/components, …) with a commit per batch. Reviewing a 400-file diff is where codemod mistakes slip through; reviewing eight 50-file diffs is tractable.

Pair with a formatter. Follow the run with vendor/bin/pint (or your formatter) so the rewritten attribute blocks match your style, then re-run Blade compilation (php artisan view:cache) to confirm nothing broke syntactically.

Contributor pattern (new in v1.2.2). If you are patching the mapping or adding support for another icon set, composer analyse, composer test, composer test-install (spins the package against Laravel 10/11/12) and composer e2e are now the documented verification path. composer e2e chains format → analyse → test → coverage → install test, so it's the one command to run before opening a PR.

Gotchas and Tips

No rollback but git. The tool rewrites files in place; there is no undo. A clean VCS state and a dedicated branch are your safety net — treat them as mandatory, not optional.

Dynamic component names are invisible to it. <x-dynamic-component :component="$icon" />, icon names built from strings ("heroicon-{$variant}-{$name}"), and PHP-side BladeHeroicons::svg() calls won't be rewritten. Grep for these patterns manually after the run — this is the most common source of "the migration worked but some icons are missing in prod".

Renames can collide. If the mapping is ordered naively, a replaced name can be re-matched by a later rule (or an -o-/-s- variant rewrite can hit the wrong segment). Diff-audit for double-substitutions, and don't run the command twice "just to be safe" — check whether it is idempotent with a --help/dry-run pass first.

Custom and third-party icons are out of scope. Any icon component you defined yourself, or one from another icon package that mimics the heroicons namespace, may get caught by a loose pattern match. Scope the run to the directories that actually use Blade Heroicons and spot-check anything unusual in the diff.

Attributes and formatting. Codemods typically swap the tag/name and leave the rest of the attribute list untouched — usually what you want, but multi-line tags and comment annotations can end up oddly wrapped. Always run Pint and view:cache afterwards.

Static-analysis config is src/-only. v1.2.2 deliberately restricts PHPStan to src/ to avoid Pest compatibility noise. If you fork the package and add tests expecting analysis, don't assume composer analyse covers them; run composer test for that.

Version risk on the tool itself is low. v1.2.2 is a tooling/coverage release — PHPStan config, an install-test script, an e2e aggregator, and one internal type fix in UpgradeIcons — with no consumer-facing API, flag, or mapping changes. Patch-bumping is safe; if you pinned v1.2.1 in CI, this is a free upgrade that gets you the Laravel 12 install verification.

Keep it dev-only and eventually remove it. Once the migration is complete and your CI guard is in place (or you've accepted the guard cost), you can drop the dependency. Leaving a codemod in require rather than require-dev is the one mistake that actually reaches production.