Nova Help Laravel Package

Technical Evaluation

Architecture fit. comodolab/nova-help is a single-purpose Nova custom field: a display-only component that renders Markdown guidance inline within a resource form. It persists nothing, validates nothing, and has no server-side behavior beyond extending Laravel\Nova\Fields\Field. Architecturally this is a leaf node — it touches no models, no migrations, no queues, no service providers beyond asset publishing. Fit is therefore binary: if the estate is Laravel Nova 4, it slots in cleanly as a presentational concern; if it is anything else (Filament, Blade admin, Retool, Nova 3, Nova 5), there is no partial fit and nothing to salvage. The capability it delivers is real but narrow: proximity of operational guidance to the input it describes, which is the cheapest known intervention against "what do I put in this field?" interruptions.

Integration feasibility. High, and bounded in effort. The integration surface is one class plus a compiled Vue asset. The genuine work is not installation but the conventions built around it: where copy lives (config vs. lang files vs. a constants class), how fields are ordered relative to their subject, and whether the pattern is standardized across resources or sprinkled ad hoc. Composer installation requires an exact pin to 0.6.0-alpha (pre-release stability), and assets require php artisan nova:publish. A competent Laravel engineer can have a working field rendered in under an hour and a codified convention in place within a sprint.

Technical risk. Three distinct risks, each manageable but each requiring an explicit decision rather than drift:

• Lifecycle risk (high). The repository is archived, has zero dependents, 57 stars, and no release since May 2022. There is no maintainer escalation path, no security-response process, and no Nova 5 roadmap. Nova 5 will almost certainly break a Vue 3 field written against Nova 4 internals, and no fix is coming.
• Version-line risk (moderate). The 0.5.x (Nova 3 / Vue 2) and 0.6.x (Nova 4 / Vue 3) lines are not interchangeable. In a multi-app estate, a shared internal package or a loose lockfile can silently install the wrong line, producing a field that fails silently in the UI rather than erroring loudly.
• Supply-chain risk (low). MIT-licensed, dependency-free, display-only, and small enough to audit in minutes. Nothing here executes with privileged data access. The blast radius of compromise is a cosmetic field.

Key questions to resolve before approval.

1. What Nova major version is each application in scope on, today and on the 12-month upgrade path?
2. Do we intend to depend on this package, or to vendor the class into app/Nova/Fields/Help.php and remove the dependency? (The source is one class; copying is legitimate under MIT and removes the lifecycle risk entirely.)
3. Who owns help copy after launch — engineers in PHP, or a documentation team? If the latter, this package is the wrong foundation and the requirement is a content workflow, not a field.
4. What is the measurable hypothesis? If the goal is support-load reduction, define the baseline question count before rollout.
5. Does approving an archived, alpha-tagged, single-maintainer package for a cosmetic concern set a precedent we are comfortable defending in a dependency-policy review?

Integration Approach

Stack fit. Requires Laravel Nova 4 specifically, with the matching Vue 3 front end. No other framework dependency is implied beyond what Nova already requires. If the estate is on Nova 4 today, fit is clean. If any in-scope app is on Nova 3, that app stays on 0.5.x — treat it as a different package wearing the same name and isolate it accordingly. If the estate is heading to Nova 5 within the planning horizon, do not adopt; budget a fork instead.

Migration path. There is no migration. The package has no schema, no persistence, and no data to move. "Migration" here means relocation of copy: pulling field-level guidance out of wikis, tribal knowledge, and inline comments into a version-controlled home. That is a content task, not an engineering one, and it should be scoped as such.

Compatibility. Pin 0.6.0-alpha exactly in composer.json — not ^0.6. Pre-1.0 plus an alpha tag permits breaking changes in a minor release, and a caret range can drift onto a stable with a changed API. If Composer objects to the pre-release, apply stability to that single requirement rather than loosening project-wide minimum-stability. Verify the real PHP/Laravel/Nova constraints in the package composer.json against pinned versions before planning around it, and confirm whether compiled JS ships in dist/ or whether a Node toolchain is required.

Sequencing. A pragmatic four-step path:

1. Audit (half day). Read src/Help.php and composer.json. Confirm the constructor and content-setter API from source, not from blog posts. Confirm the asset situation.
2. Reference implementation (one to two days). Install pinned on a single Nova 4 app. Place one help field directly above the single field operators most reliably get wrong. Add ->onlyOnForms() and ->hideFromIndex() so no blank guidance column appears in index tables. Give the field a subject-specific name to avoid attribute-key collisions.
3. Convention (one sprint). Decide where copy lives — language files are preferable to config for cache-safety and future localization; wrap every string in __() from day one. Add a thin app-level factory (App\Nova\Help\Guidance) so resource classes stay terse. Codify the rule: guidance blocks sit adjacent to their subject, and Nova's native ->help() remains the tool for one-line hints.
4. Decide depend vs. copy (before rollout widens). Given archived status, the default recommendation is to fork the class into the application namespace and drop the Composer dependency. The UX win is preserved; the version treadmill disappears; the cost is approximately half an engineer-day — less than the procurement and policy conversation required to justify a maintained-dependency exception.

Recommendation to stakeholders. On Nova 4, with a need this quarter and a small team, adopting the pinned pre-release is defensible as a reference implementation only. Across a multi-app estate, a long-horizon platform commitment, or any pending Nova 5 upgrade, reimplement rather than depend.

Operational Impact

Maintenance. The dominant operational fact is that upstream is archived. There is no maintainer, no release cadence, no security-response channel, and no path to a fix. Practical consequence: every Nova major upgrade becomes a re-verification project for every resource carrying a help field. If the team copies the class into application code, that obligation converts from an external dependency risk into ordinary owned-code maintenance — a strictly better position for something this small.

Support. Support surface is minimal on the engineering side and genuinely positive on the operations side, which is the point of the package. The failure operators will actually encounter is a field that renders blank or unstyled; the triage order is asset published → caches cleared → browser console checked for Vue errors. Document that runbook once. The support risk to flag is authorship: if non-engineers are expected to update copy, text baked into PHP field definitions is not a content workflow, and the resulting friction will quietly kill adoption.

Scaling. Scales trivially on the technical axis — it is a presentational field with no runtime cost, no queries, no external calls. It does not scale on the content axis. Thirty resource classes each with inlined paragraphs is how guidance goes stale with no way to find it. The scaling answer is the factory-plus-lang-file convention, plus a light test asserting that key resources still carry their guidance fields — the cheapest defence against copy silently vanishing in a refactor. Note also the hard ceiling: no modals, no searchable docs, no per-locale switching, no analytics on which help text is opened. If any of those appear on the roadmap, this package is not the foundation and a bespoke field is the honest answer.

Failure modes. Enumerated by likelihood and severity:

• Silent non-render (likely, cosmetic). Vue 3 field on a Vue 2 host, or unpublished assets. Degrades to a blank field; no workflow or data impact. This is the acceptable worst case and the reason the risk is approvable at all.
• Version drift (moderate, cosmetic). A caret range pulling an incompatible pre-1.0 release. Mitigated by exact pinning.
• Cross-estate version mixing (moderate, confusion-heavy). Nova 3 and Nova 4 apps sharing a lockfile or internal package. Mitigated by explicit per-app pinning.
• Stale copy (high likelihood over time, low severity). Guidance diverges from reality and trains operators to ignore it. Mitigated by convention, ownership, and linking to policy rather than pasting it.
• Nova 5 upgrade (certain on that path, moderate severity). Field breaks; no upstream fix. Mitigated only by forking.
• Content injection (low). If the Markdown renderer passes raw HTML, never interpolate request data or model attributes into copy. Verify escaping from source; treat content as engineer-authored static text only.

Ramp-up. Effectively zero for any engineer already fluent in Nova. The class is one file and readable in five minutes. The realistic ramp cost is organizational, not technical: agreeing the convention, deciding where copy lives, assigning ownership, and resisting the temptation to inline entire runbooks. Budget one sprint from first install to a standardized pattern across a handful of high-value resources, and define the success measure up front — for example, a count of "what does this field mean?" interruptions in the four weeks before and after rollout. Without a baseline, the initiative cannot be defended at the next planning cycle, and an archived dependency with a cosmetic payoff is exactly the kind of item that gets cut when nobody can show it worked.