Nova Help Laravel Package

Getting Started

Check your Nova major before you type a single command. This is a Nova custom field — a display-only field that renders text inside a form panel. It means nothing outside Nova, and the version line is the compatibility story: 0.6.0-alpha is the Nova 4 / Vue 3 build, 0.5.x is Nova 3 / Vue 2. There is no Nova 5 release and the repository is archived, so whatever you install is what you get, forever.

composer require comodolab/nova-help:0.6.0-alpha
php artisan nova:publish

If Composer refuses the pre-release, scope stability to that single requirement ("comodolab/nova-help": "0.6.0-alpha@alpha") rather than loosening minimum-stability for the whole project.

Read these three things first, in this order:

1. vendor/comodolab/nova-help/src/Help.php — the field is essentially one class, five minutes end to end. The exact constructor and content-setter names (text(), content(), or similar) come from here, not from a blog post; the README drifted during the alpha.
2. vendor/comodolab/nova-help/composer.json — the real PHP / Laravel / Nova constraints. Compare against your pins before you plan around it.
3. dist/ — whether compiled JS ships with the package, or whether you'd need a Node toolchain to build it.

Publish the config if the provider exposes one:

php artisan vendor:publish                              # list tags first
php artisan vendor:publish --provider="Comodolab\NovaHelp\HelpServiceProvider"

First use case: pick the one field your operators most reliably get wrong — a status enum, a JSON payload, a money amount with a unit convention — and put a single help field directly above it. Nothing else.

use Comodolab\NovaHelp\Help; // confirm namespace + method in src/Help.php

public function fields(NovaRequest $request): array
{
    return [
        Help::make('Order status guidance')
            ->text('Set to **Fulfilled** only after the courier scan is logged. If the scan is missing, leave it at *Processing* and file a ticket.')
            ->fullWidth()
            ->onlyOnForms(),

        Select::make('Status')->options([...]),
    ];
}

Then look at the form as an operator. If nobody would read the block, delete it. The entire value here is proximity to the input, not the existence of the text.

Implementation Patterns

Keep copy out of resource classes. Inlining paragraphs across thirty fields() methods is how instructions go stale with no way to find them. Pick one home and commit:

• config/nova-help.php — only if the package's config-driven content model actually fits your shape; remember it is config-cached.
• lang/en/nova-help.php, referenced as __('nova-help.orders.status') — better for translation and immune to config-cache confusion.
• A small App\Nova\Help\Text constants class — greppable, diffable, no indirection.

Wrap every string in __() from day one, even with one locale. It costs nothing now and is the difference between a one-day and a one-week localization task later.

Add a thin app-level factory so resources stay terse and the convention lives in one place:

// app/Nova/Help/Guidance.php
public static function orderStatus(): Help
{
    return Help::make('Order status guidance')
        ->text(__('nova-help.orders.status'))
        ->fullWidth()
        ->onlyOnForms();
}

Ordering is the pattern. Nova renders fields in array order. A guidance block sitting three fields away from its subject is worse than no guidance at all — the operator reads it out of context and it becomes noise.

Separate the two registers of help text. Nova's native ->help() is correct for a one-line hint underneath the input (ISO 4217, e.g. EUR). This field is for multi-sentence guidance, a warning above a destructive action, or a link to a runbook. Using a paragraph field where a hint belongs trains people to ignore both.

Link to policy, don't paste it. Markdown support makes it tempting to inline the whole runbook. Link the wiki page instead — the codebase should not become the system of record for procedures that change without a deploy.

Scope visibility with the inherited Nova field methods: ->onlyOnForms(), ->hideFromIndex(), ->canSee(fn ($request) => $request->user()->isAdmin()). A guidance column rendering blank inside the index table is the classic avoidable annoyance.

Treat it as a convention, not a one-off. The leverage is in standardizing "every resource with a genuinely confusing field carries one guidance block." Add a light test asserting those fields exist on your key resources — the cheapest defence against copy silently vanishing in a refactor.

Plan the fork before you need it. The class is small and MIT-licensed. Copying it to app/Nova/Fields/Help.php and dropping the dependency is half a day and removes the version treadmill entirely. If you take the dependency, note in the upgrade checklist that a Nova major likely means forking.

Gotchas and Tips

Pin the exact version. "comodolab/nova-help": "0.6.0-alpha", not ^0.6. Pre-1.0 plus an alpha tag means semver permits breaking changes in a minor, and a caret range can drift you onto a stable with a changed API.

A blank field is almost always an asset problem, not a PHP problem. In order: confirm the asset was published (php artisan nova:publish), clear caches (php artisan view:clear config:clear), then open the browser console and look for Vue errors. A Vue 3 field on a Vue 2 host fails silently in the UI. Check composer show comodolab/nova-help before debugging anything else.

Never mix version lines across a multi-app estate. Nova 3 apps stay on 0.5.x; Nova 4 needs 0.6.x. If you run both, you have two different packages wearing the same name, and a shared internal package or lockfile will bite you.

It persists nothing — so don't validate it. No ->rules(), no ->required(), no ->sortable() on a display-only field. Rules belong on the real field underneath, and it must not appear in a fields() array used for indexQuery ordering.

Give each help field a unique name within a resource. Two Help::make('Guidance') entries in one form can collide on the attribute key. Name them for their subject: 'Order status guidance', 'Refund policy'.

Treat the content as trusted input. If the markdown renderer passes raw HTML through, never interpolate request data, model attributes, or anything user-supplied into the copy. Static text authored by engineers only. Verify the escaping behaviour from source rather than assuming it.

Config cache freezes your copy. If guidance lives in config/nova-help.php, editing a paragraph requires php artisan config:cache on deploy before the change appears. Language files avoid this whole class of confusion.

Nova 5 is unproven and will probably break it. A Vue 3 field written against Nova 4 internals is exactly what a major bump invalidates — and the repo is archived, so no fix is coming. Add "re-render every resource with help fields" to the Nova upgrade checklist, not just "composer update succeeded."

Debug by simplification. If a field misbehaves, strip it to Help::make('X')->text('hello') with no fullWidth(), no canSee(), no config indirection. If that renders, the problem is your content pipeline; if it doesn't, it's the asset/version layer.

Extension points are thin by design — that's fine. You get a Nova field plus the layout and visibility methods inherited from Laravel\Nova\Fields\Field. If you need modals, searchable docs, per-locale switching, or analytics on which help text gets opened, this package is not the foundation for that; write the field yourself.