Nova Breadcrumbs Laravel Package

Getting Started

Verify compatibility before you write a line of code. Last release was 2023-04-25, there are zero dependents, and the package hooks Nova's breadcrumb rendering rather than a public contract. Run composer show formfeed-uk/nova-breadcrumbs --all and compare the declared Nova/Laravel/PHP constraints against your actual composer.lock. Do the install on a staging clone and never on main first.

Minimal install sequence:

1. composer require formfeed-uk/nova-breadcrumbs:3.1.2 — pin the exact patch. 3.1.2 fixes a duplicated Nova path in the home breadcrumb; you do not want to sit below it.
2. Confirm auto-discovery, or register the provider manually in config/app.php.
3. Publish the config if the README lists a vendor:publish tag (php artisan vendor:publish --tag=...) and commit the published file so the config is reviewable in PRs.
4. Register your first trail from app/Nova/NovaServiceProvider.php::boot().
5. Load a Nova page in the browser and confirm the crumb renders before writing a second one.

Where to look first. Read all of vendor/formfeed-uk/nova-breadcrumbs/src/ — it's small, and it tells you exactly which Nova internals you're depending on. Then diff its service provider against Nova's first-party breadcrumb component so you know what you're displacing and what breaks if the package is removed mid-sprint.

First use case: a custom tool page, not a resource index. Nova handles resource indexes reasonably well already, so a resource index gives you no signal about whether your override is even active. Custom tools and dashboards are where native trails are weakest — that's where the package earns its keep and where a broken install is obvious.

Implementation Patterns

Pick one registration strategy and never mix it. Scattering crumb definitions across the provider, every tool's boot(), and individual resource classes is how you end up with trails nobody can trace.

• Central registry: one app/Nova/Breadcrumbs.php (or a config map keyed by route name), called once from the provider. Best when the logic is uniform across many resources and overrides are mostly relabeling.
• Resource-local: a static breadcrumbs() method on each Nova\Resource, invoked from the provider via a loop over Nova::availableResources(). Best when a trail depends on that resource's own relationships and you want navigation to live beside the thing it describes.

Either way, the whole thing collapses to one file when you fork or replace the package — which is the point.

Resolve crumbs lazily, from named routes. Define crumbs inside a closure that runs at render time, not at boot time. Never concatenate paths or hardcode /nova/resources/.... Lazy resolution is what makes trails survive localized route prefixes, tenant-scoped Nova paths, and Nova's own path configuration.

// Illustrative — confirm the exact registration method in vendor/src.
Breadcrumbs::for('nova.projects.detail', fn ($project) => [
    ['label' => 'Clients', 'url' => route('nova.clients.index', ['client' => $project->client_id])],
    ['label' => $project->client->name, 'url' => route('nova.clients.detail', $project->client_id)],
    ['label' => $project->name],
]);

The pattern that actually matters: prepending a contextual parent. Most real requirements aren't relabeling Nova's crumbs — they're adding a parent Nova doesn't know about, so a "back" link lands on a filtered index (?client=5) rather than the unfiltered one. A back-link that silently drops the user's filter is worse than no link.

Per-tool trails belong in the tool's own boot(). That way the crumb definition ships with the tool if you ever extract it into a package, and it stays visible to whoever owns that tool.

Gate crumbs explicitly. A breadcrumb is a URL, not a canViewAny() check. Emitting a crumb to a resource the user can't view produces a 403 on click — a worse experience than omitting the crumb. Wrap the conditional in the same closure that builds the label.

$crumbs = [];
if (Gate::allows('viewAny', Client::class)) {
    $crumbs[] = ['label' => 'Clients', 'url' => route('nova.clients.index')];
}

Write one feature test. Hit a Nova route as an authenticated user and assert the expected crumb label appears in the response body. Twenty lines, and it's your only automated defense against a silent regression on the next Nova upgrade.

Gotchas and Tips

The failure mode is silent. Breadcrumbs almost never throw — they render the wrong parent, drop a link, or duplicate a segment. Every verification step must assert on rendered output. A crumb quietly pointing at the wrong tenant's dashboard is a correctness bug, not cosmetics.

Watch the home crumb. The 3.1.2 fix came out of home-path handling, and overriding home is the single largest source of duplication. Define home in exactly one place. If it's set both in the package config and via Nova's own home path, you'll get doubling.

Clear the config cache after every trail edit. If a crumb defined in config refuses to change, it's php artisan optimize:clear, not a package bug. This costs twenty minutes at least once.

Boot order determines whether a tool's crumbs appear. If they're missing, the tool may be booting after your provider, or the request isn't inside Nova's middleware group at all. Check Nova::availableTools() and the route registration before debugging the package.

No database queries in crumb closures. Crumb resolution runs on every Nova page render. If you need a parent record's name, take it from data the page has already loaded or cache the lookup. A crumb issuing a SELECT on every admin page load is trivial to ship and hard to notice.

Add a breadcrumb line to your Nova upgrade runbook. Given the 2023 release date, a manual smoke check across resource index, resource detail, create/edit, one custom tool, and a dashboard is not optional. Assume minor Nova upgrades can break this until proven otherwise.

Treat it as vendored from day one. MIT, one maintainer, no releases in over two years. Copy vendor/formfeed-uk/nova-breadcrumbs into packages/ behind a Composer path repository before it breaks, name an owner for the fork, and keep all custom logic in your own app code — never patched into vendor/.

Know where the abstractions end. The moment requirements become permission-aware trails across tenants, dynamic multi-level hierarchies, or cached lookups, native implementation is cheaper than fighting this package. Simple label and link overrides: use the package. Anything stateful: write and test it yourself.