Nova Fields Help Laravel Package

Getting Started

1. Install the package via Composer (it uses Laravel package auto-discovery):

   composer require marshmallow/nova-fields-help:^3.1
   

   As of 3.1.0 the package tracks current Laravel — including Laravel 13 support landed in PR #105. If your app is pinned to an older Laravel major, check composer.json's require block before upgrading; if the constraint excludes you, stay on the 3.0.x line rather than forcing the install with --ignore-platform-reqs.

2. Check the README first, then src/. Documentation is still minimal relative to the field's flexibility. Open vendor/marshmallow/nova-fields-help/README.md and, more importantly, the field class and its resources/js/components/ Vue file — those tell you the real API (method names, props, defaults) faster than any blog post.

3. Confirm the service provider boots. If auto-discovery is disabled, register the provider in config/app.php. Nova field packages ship a dist/js/field.js that Nova auto-loads — if nothing appears, run:

   php artisan vendor:publish --provider="Marshmallow\NovaFieldsHelp\FieldServiceProvider" --tag=assets
   

4. First use case — drop a help block into a resource form to explain a tricky field group:

   use Marshmallow\NovaFieldsHelp\Help;
   
   public function fields(Request $request)
   {
       return [
           Help::make('Billing help')
               ->text('Invoices are generated on the 1st of each month.'),
           // ...your actual fields
       ];
   }
   

   Load the resource in Nova, verify the help block renders above/below the intended field, then wire it into the rest of your resources.

Implementation Patterns

Inline field documentation. The primary pattern: place a Help instance immediately before any field whose meaning isn't obvious to ops users (foreign keys, status enums, currency fields). Because it's a Nova Field, it slots into the fields() array without touching the underlying model.

Contextual display. Nova fields expose showOnIndex, showOnDetail, showOnForms, hideFromIndex, etc. Help text is almost always form-only:

Help::make('Shipping notes help')
    ->text('Leave blank to use the warehouse default.')
    ->showOnForms()
    ->hideFromIndex()
    ->hideFromDetail();

This prevents the help block from polluting index tables and detail views where it's noise.

Grouping and layout. Wrap help text inside Nova's native layout primitives (Panel, Section, Field::make(...)->help() where available) so callouts stay attached to the section they describe. A common workflow is a Section::make('Pricing', [...Help::make(...)->text(...), Currency::make(...)]).

Markdown or HTML content. If the package supports it (check the field's text() / content() setter), pass Markdown for anything longer than a sentence. Otherwise pass an inline string; avoid mixing raw HTML unless you've confirmed the Vue component uses v-html — most Nova help fields render via v-text for safety.

Reusable snippets. Since help copy often repeats (payment terms, tax rules), extract a private method or a trait on the resource:

private function pricingHelp(): Help
{
    return Help::make('Pricing help')->text('Prices exclude VAT.');
}

Then include it in every resource that touches pricing. This is far cleaner than duplicating strings — and it keeps the swap cost low if the package ever changes hands.

Custom tools and cards. Help text isn't limited to resource forms — the field can be used inside Nova custom tools' Vue components if it ships a registered field component. Check nova-components/ or resources/js/tool.js in your app to see if a registration exists; if not, you'd import the field component directly (require('../../vendor/.../resources/js/components/Field')).

Theming integration. Nova 4+ ships Tailwind; if the package uses Tailwind utility classes, help text inherits your Nova theme. If you need a distinct visual style, add a class via the field's withMeta or an extraAttributes method (check the source — not every small package exposes these).

Gotchas and Tips

• Don't add it to $fillable. Help is a display-only field — if you accidentally pass it through fill(), Laravel will complain about a missing column. Keep it out of request validation and $fillable entirely.

• Asset cache after upgrade. Nova caches compiled JS. After any composer update on the package, run:

  php artisan nova:publish
  php artisan optimize:clear
  

  then hard-refresh the browser. Most "I upgraded and the field broke" reports on small Nova packages are stale public/vendor assets.

• Nova version compatibility. The 3.1.0 release widened Laravel support, but that says nothing about Nova's field API. Check composer.json's require block for laravel/nova (likely ^4.0 / ^5.0). Laravel 13 support does not imply Nova 5 support — Nova versions and Laravel versions move independently, so verify both constraints before upgrading. Test a Nova major bump in a branch first; Nova's field API has shifted (resolve signature, fill semantics) between majors.

• Laravel 13 in CI only if the rest of the matrix is ready. Adding a Laravel 13 job is cheap; bumping your app to Laravel 13 because the package "supports" it is not. Treat 3.1.0 as a compatibility widening, not a mandate — upgrade Laravel on your own schedule.

• Component name collisions. Nova field packages register a global Vue component (e.g. help-field). If another package uses the same name, one silently wins. Inspect the browser console for [Vue warn]: Component already registered and check resources/js/field.js for the Nova.booting hook.

• Debugging an empty render. If the help field shows nothing: (a) confirm the service provider is loaded, (b) inspect the DOM for a <div> with your field's component class, (c) if it's there but empty, the issue is the text() payload — log it in resolve() to confirm the meta is set. If the <div> is absent, it's a JS registration issue, not a data issue.

• Extension points worth checking in source. Look for ->withMeta(), ->help(), ->heading(), and any resolveUsing override. Small Nova packages frequently expose 2–3 chainable meta setters that aren't in the README. Grepping the field class for $this->withMeta reveals them all.

• Maintained, but still thin. 3.1.0 shows a live repo: community PRs merged, Dependabot active, a first-time contributor onboarded. That's a healthy signal and reduces the abandonment risk. It doesn't change the architecture, though — this remains a Field::make() with ->component('help-field') and a small Vue component. Keep help strings centralized (see "reusable snippets") so a future swap is a use statement change, not a refactor.

• Pin and review diffs. Pin "marshmallow/nova-fields-help": "^3.1" and read the changelog before upgrading in CI. For 3.1.0 the diff is two PRs — a Laravel constraint widening and a CI action bump — so it's safe. Patch releases on this package have historically been small; treat any future minor with a glance at composer.json rather than a full regression pass.