Nova Help Laravel Package

Getting Started

• Check your Nova version first. v3.0.0 is a hard breaking change: nova-help now requires Nova 5 and ships a rebuilt, minimal-footprint frontend for Nova 5's asset pipeline. If the app is still on Nova 4, stay on ^2.0; do not attempt to composer require clevyr/nova-help:^3.0 alongside Nova 4 — the constraint will (correctly) fail to resolve.
• Upgrade order matters. Upgrade laravel/nova to 5 and get php artisan nova:publish clean before bumping this package. Then composer require clevyr/nova-help:^3.0, run php artisan optimize:clear, and hard-refresh Nova.
• Where to look first: the README for the current registration snippet, src/ for the card/field class and any config, and dist/js/ for the compiled component. Because v3 optimizes for "minimal footprint," expect the public surface to be small — one class, one component, no publishable config beyond what the README documents.
• First use case: drop a help panel onto the resource screens your content editors actually use (create/edit forms for the models with the most custom fields), containing conventions, link formats, and "who to ask" text. It is the cheapest way to stop the same Slack questions without touching a docs site.

Implementation Patterns

• Dashboard card. Register in NovaServiceProvider::cards() (or your Main dashboard's cards()) and pass markdown as the card's content. Best for org-wide onboarding text, environment banners ("this is staging"), and links to internal runbooks.
• Per-resource help. Give each resource a small help block keyed off the resource class — a config/nova-help.php map of Resource::class => 'help.resources.orders' plus lang/markdown files keeps copy out of PHP and makes it reviewable in PRs.
• Keep content in files, not closures. Store markdown under resources/lang/{locale}/help/*.md or resources/views/help/*.md and render with Str::markdown() / __() so copy changes never require a deploy of PHP logic, and translations ride the same pipeline as the rest of the app.
• Field-level placement. Where Nova's built-in help() text is too cramped, place the card adjacent to the relevant field group on the form so the explanation sits next to the inputs it describes rather than in a separate panel.
• Gate visibility. Help cards are visible to every Nova user by default; use canSee/canSeeWhen to hide internal-only content (support runbooks, refund procedures, admin contact details) from non-admin roles.
• Compose with your own card when you outgrow it. If you need tabs, collapsibles, or live status, don't fork the package — wrap it or replace it with a custom Nova card and keep this one for static copy.

Gotchas and Tips

• There is no dual-version support. Treat v3 as a fork in the road: Nova 4 apps pin ^2.0 indefinitely, Nova 5 apps take ^3.0. If you maintain both, say so explicitly in composer.json per branch rather than trying a wide constraint like ^2.0|^3.0, which will silently install the wrong build on the wrong Nova.
• Nova is not on public Packagist. CI images and fresh containers need Nova credentials (composer config http-basic.nova.laravel.com …) or the upgrade step fails in CI while passing locally. This is the single most common cause of a "broken" v3 update.
• Asset caching after upgrade. A blank or unstyled card after bumping versions is almost always stale compiled assets or a stale mix-manifest. Run php artisan nova:publish, php artisan optimize:clear, then hard-refresh; check the network tab for a 404 on the card's dist/js bundle before you debug PHP.
• Markdown, not HTML. Nova's renderer sanitizes; raw HTML, inline styles, and <script> will be stripped. Verify tables, fenced code blocks, and deeply nested lists render in the actual Nova 5 theme — the visual styling changed between Nova 4 and 5.
• Long content scrolls. A card full of prose becomes unusable on a laptop screen. Keep each card under ~15 lines, prefer short bullets and links out to the full doc, and split topics across cards instead of one wall of text.
• Don't fork to restyle. If views/styles are publishable, publish and edit them in the host app so composer update doesn't clobber your changes. If they aren't, wrap the component instead of editing dist/.
• Keep the changelog link handy. Diff v2.0.0...v3.0.0 before upgrading any app that customizes the card; the "minimal footprint" rewrite may have changed the component name or props even beyond the Nova 5 requirement.