Blade Heroicons Upgrader Laravel Package

Technical Evaluation

Architecture fit. blade-heroicons-upgrader is a dev-tooling package, not runtime infrastructure: it ships an artisan command (UpgradeIcons) that rewrites Heroicons references in Blade templates. Architecturally it sits alongside other one-shot codemod tooling (Rector, Laravel Shift-style upgraders) rather than in the request path, so it carries no production runtime surface, no service provider boot cost that matters, and no schema or queue implications. That is a favourable risk profile for adoption, but it also means the package's value is bounded to a single migration event — it is disposable by design.

Integration feasibility. High. It is a Composer require-dev dependency targeting Laravel 10/11/12. The v1.2.2 release materially improves the evidence base for integration: an automated test-install.sh exercised across Laravel 10, 11, and 12 gives us a matrix claim we can verify rather than assume, and composer e2e (format → analyse → test → coverage → install-test) means a single command reproduces the maintainer's full gate. PHPStan configuration scoped to src/ is a reasonable, deliberate trade-off (Pest compatibility) but tells us static analysis does not cover the test suite — a minor coverage gap, not a blocker.

Technical risk. Low-to-moderate, concentrated in three places:

1. Source-rewriting risk. Codemods that mutate Blade files are the highest-consequence class of dev tool — a bad regex can silently corrupt templates. 100% test coverage on the interactive prompt path is reassuring but coverage of the rewrite logic itself is not demonstrated in these notes.
2. Idempotency and dry-run. Release notes are silent on --dry-run, backup, or diff-preview capability. This is the single most important safety affordance for this tool category and must be confirmed before we point it at a real codebase.
3. Analysis blind spot. PHPStan scoped to src/ only means type regressions in the test harness (including test-install.sh's companion code) are not statically caught; the v1.2.2 UpgradeIcons string-typing fix is exactly the class of bug that only surfaces at analysis time, which suggests this gate is doing real work.

Key questions.

• Does UpgradeIcons support dry-run/diff output and idempotent re-execution? What is the rollback story if a run corrupts templates?
• Are Heroicons v1 → v2 mappings complete, and how are ambiguous/renamed icons handled — fail loudly or skip silently?
• Is test-install.sh run in CI on every commit, or only locally via composer test-install? CI enforcement is what makes the Laravel 10/11/12 claim durable.
• What is the exit-code contract on partial failure, and is it safe to run inside a CI job?
• Maintenance posture: single maintainer? Release cadence (v1.2.1 → v1.2.2 suggests active but small-surface maintenance)?
• Is src/-only PHPStan a permanent decision or a temporary workaround pending Pest/PHPStan compatibility?

Integration Approach

Stack fit. Fits any Laravel 10–12 application using blade/heroicons (or vendored Heroicons) with Blade templates. No conflict with frontend build tooling since it operates on .blade.php sources rather than compiled output — but that also means it must run before any build step and its output must be reviewed as source diffs, not artifacts.

Migration path. Treat this as a contained, time-boxed migration workstream:

1. Add as require-dev, pin the version explicitly (do not use a floating constraint for a file-mutating tool).
2. Run against a scratch branch or a sparse checkout of the highest-traffic template directories first.
3. Diff-review output; reconcile ambiguous icon renames by hand.
4. Expand to the full template tree, then run the app's own Blade compile/lint gate.
5. Remove the dependency once the migration lands.

Compatibility. Laravel 10/11/12 is now test-backed rather than asserted — that is the substantive improvement in this release and the main reason it changes our confidence level. PHP version support is not stated in the notes and should be confirmed from composer.json. Pest-based test suite implies PHP 8.1+ at minimum; confirm against our oldest supported runtime.

Sequencing. Low-coupling, high-ordering-sensitivity. It must run after any Heroicons package version bump and before frontend asset rebuilds and visual regression baselines. If we are mid-flight on a design-system icon refresh, sequence this tool first so the codemod sees the old naming and the manual work sees the new. Do not run concurrently with other Blade-mutating tooling (e.g. Pint/Blade formatters on the same working tree) — serialise to keep diffs attributable.

Operational Impact

Maintenance. Near-zero ongoing cost if the dependency is removed post-migration, which should be the default plan. If retained, it becomes a dev-dependency we must keep PHP-compatible with our matrix — a small but non-zero tax for a tool used once.

Support. No vendor relationship; support is GitHub-issue-based on a small project. Acceptable for dev tooling with a short usage window and unacceptable as a permanent build-pipeline dependency. Internal ownership should sit with whoever owns the design-system/frontend platform, not with application teams.

Scaling. Effectively irrelevant in the runtime sense — no throughput, latency, or concurrency characteristics. The scaling dimension that does apply is blast radius across a monorepo: N applications × M templates means the tool is run many times, so idempotency and predictable exit codes matter more than speed. For large template trees, confirm the command completes without memory issues and can be scoped by path.

Failure modes.

• Silent mis-rewrite — worst case; caught only by diff review and visual regression. Mitigate with dry-run (if available) and small-batch execution.
• Partial application — run aborts mid-tree leaving inconsistent naming; mitigate with a clean git state before each run so git diff/git checkout is the undo.
• Silent skip of unmapped icons — leaves stale references that fail at render; mitigate with a post-run grep for the old icon naming convention.
• Static-analysis false confidence — PHPStan covering only src/ means our own wrapper scripts and the test harness are unanalysed; do not extend our trust boundary to them.
• New tooling churn — composer e2e/test-install are maintainer-facing and irrelevant to consumers; avoid copying them into our CI.

Ramp-up. Very low — one command, one flag set. Half a day for a developer to run a pilot on a representative template slice and write up the diff-review checklist. The real ramp-up cost is organisational, not technical: establishing the review protocol for machine-edited Blade files, since that is a novel change type for most teams and reviewers will otherwise rubber-stamp large diffs.

Net recommendation. Adopt as a scoped require-dev migration utility, pinned, on a short-lived branch, with mandatory diff review and a plan to remove it. The v1.2.2 release does not change the tool's capability surface — it strengthens the quality signal (multi-version install testing, 100% coverage, enforced static analysis) and fixes one type bug. That raises confidence in the maintainer's engineering discipline, not in the tool's feature completeness; the dry-run/idempotency questions above remain the gating unknowns before we commit to a full-tree run.