Nova Icon Field Laravel Package

Technical Evaluation

Architecture fit. This is a Nova field, not a standalone icon library. It has value if and only if the admin surface is Laravel Nova 4 — there is no fallback story for Blade-only, Filament, or Inertia front ends. Where Nova is the admin, the fit is unusually clean: Icon::make('Icon')->setIconSets([...]) is a pure presentation adapter that persists a plain string(255) identifier. No JSON blobs, no polymorphic relations, no package-owned tables. Storing the neutral identifier (account-group) rather than a rendered class (mdi mdi-account-group) keeps the data portable and means a future icon-library swap is a config change, not a migration. That is the architecturally correct decision and it is the one the package nudges you toward.

Integration feasibility. Low effort, high constraint density. Roughly: composer require, vendor:publish --tag=nova-icon-field-config, one nullable string column, one field entry in fields(). A one-day spike covering a single resource is realistic; 1–2 dev-days to productionize once you add server-side membership validation, the identifier→render mapping, and seed data. The real work is not the dependency, it is the two artefacts you must build alongside it: a validation rule (Rule::in(...) derived from the JSON set) and an app-side mapping layer that resolves identifiers per surface. Neither ships with the package.

Technical risk.

• Nova major-version drift — the headline risk. Last release 2023-04-27; Nova 4 and Nova 5 have diverged in field APIs. A patch bump does not track a new Nova major, and there is no indication this package does.
• Bus factor of one — 2 stars, a single maintainer, and a v1.0.2 release whose notes are a changelog link only. Treat this as "we are adopting source we may have to own," not "we are adopting a supported product."
• Payload weight — icon metadata ships to the browser. Material Design Icons alone is thousands of entries; the picker does client-side filtering with no lazy loading. First-paint on Nova forms degrades on slow admin connections.
• No server-side existence check — Nova saves whatever string arrives. Any API or import path bypasses the picker entirely, so the column is only as trustworthy as the validation you add.
• Licensing shape — MIT package, but Nova itself is commercial. The dependency inherits that constraint; it is not usable outside a licensed Nova install.

Key questions to resolve before committing.

1. Which Nova major(s) are in the fleet, and is a Nova 5 upgrade on the 12-month roadmap? If yes, this package is a migration liability, not a shortcut.
2. What is the actual icon catalogue size we need per attribute? Can we trim the JSON to that subset rather than shipping a 7,000-entry set?
3. Who owns the identifier→render mapping, and where does it live (config, enum)? Is that owner identified before data exists?
4. Is the icon column authoritative or cosmetic? If authoritative or API-exposed, validation is a launch blocker.
5. Do the requirements include multi-select, custom uploads, or a user-generated/remote asset library? Any of those disqualifies this field — it is the wrong layer, and bending it ends in a fork.
6. If the maintainer abandons it, is forking cheaper than a thin in-house field? For a picker this small, an in-house field over our own JSON is a credible Plan B and should be sized now, not later.

Integration Approach

Stack fit. Laravel + Nova 4 + Composer. The field renders inside Nova resources; the front end stays fully decoupled because the stored value is a library-neutral name. That decoupling is the integration's main asset — protect it by forbidding full CSS classes in the database.

Migration path. Purely additive and reversible. Add a nullable() string column, ship the field, backfill. Existing free-text columns (fa fa-star) will not match picker identifiers — backfill through a lookup table, keep the field nullable until coverage is complete, then tighten with required + Rule::in. Rollback is trivial: remove the field from fields() and the column remains inert. No destructive step exists at any point, which keeps the change cheap to reverse if adoption stalls.

Compatibility.

• Pin ^1.0 in composer.json; never track dev-main.
• Check the README compatibility matrix against the pinned Nova version before adoption, and re-check on every bump.
• vendor:publish does not overwrite an existing config — new keys in a patch release can silently fail to appear. Diff the published config against the vendor copy on every upgrade.
• After any bump: php artisan nova:publish plus a hard browser refresh, or a stale compiled field will present old behaviour and get misdiagnosed as a regression.

Sequencing. Do not widen adoption before the surrounding scaffolding exists.

1. Branch spike with one small icon set on a low-traffic resource.
2. Define the identifier→render mapping (config or enum) before writing any data.
3. Add server-side membership validation in the same change as the field — not as a follow-up.
4. Backfill one legacy column end to end, confirming the lookup table is complete.
5. Only then scope sets per field and roll out across resources.

Scope icon sets per field, not globally. A "brand logo" attribute and a "status badge" attribute should never share a catalogue.

Operational Impact

Maintenance. The dependency surface is genuinely small — one Composer entry, one config file, one JSON set per set used. Ongoing cost lives in three places instead: the mapping layer, the icon-curation decision (who approves a new icon, who trims the JSON), and the annual Nova-compatibility check. Budget roughly one engineer-day per year for bump-and-verify, plus the fork contingency. Verify the published config after every upgrade as a standing checklist item.

Support. There is no vendor. At 2 stars, community support is effectively zero — we are the support tier. Escalation path is read the source (it is small) or fork. The highest-leverage support investment is a short runbook covering the two failure modes that will generate the most tickets: an empty or 404-ing grid means a setIconSets() key that does not match the config, or a bad JSON path; stale behaviour after an upgrade means asset cache, not a regression. Tier-1 should not burn cycles rediscovering these.

Scaling. Throughput is a non-issue — it is static JSON served from Nova assets with no server round trips for search. The scaling axis is payload, not QPS: trim JSON to the used subset, keep heavy index screens scoped to small sets, and expect the first-paint cost to surface first on slow admin connections. Note the corollary of client-side search: there is no search infrastructure to scale, but also no server-side relevance, so "I can't find the icon" almost always means the user is searching the wrong set. That is a UX/curation problem, not a paging one.

Failure modes.

• Config key mismatch → empty grid (the #1 mode by volume).
• Config entry pointing at a missing or moved JSON file → 404 / empty picker.
• Nova major upgrade breaks the field contract → form errors across every resource using the field.
• Maintainer abandonment → no Nova 5 path, forcing a fork or rewrite at a moment we do not choose.
• Invalid values arriving via API or import, bypassing the picker → dirty data in an authoritative column.
• Icon-library drift between admin and public site if anyone stores full class names instead of neutral identifiers.

Ramp-up. Near zero for a Laravel developer — an hour to a working field. The non-obvious learning is discipline, not API: publish and diff the config, scope sets per field, store the neutral identifier, add Rule::in from day one. That is a document, not a training programme. The TPM action is to make those four rules review criteria in the PR that introduces the field, because they are cheap to enforce at introduction and expensive to retrofit after data exists.